diff --git a/packages/boxel-cli/api.ts b/packages/boxel-cli/api.ts
index cdbb610d283..7f4fcbcfe04 100644
--- a/packages/boxel-cli/api.ts
+++ b/packages/boxel-cli/api.ts
@@ -19,6 +19,13 @@ export {
   type CancelIndexingResult,
 } from './src/lib/boxel-cli-client';
 
+export {
+  getToolDefinitions,
+  requireStringArg,
+  type BoxelToolDefinition,
+  type BoxelToolConfig,
+} from './src/lib/tool-definitions';
+
 export {
   resetProfileManager,
   setProfileManager,
diff --git a/packages/boxel-cli/src/commands/realm/push.ts b/packages/boxel-cli/src/commands/realm/push.ts
index 043532bc0fa..50ef03c53f8 100644
--- a/packages/boxel-cli/src/commands/realm/push.ts
+++ b/packages/boxel-cli/src/commands/realm/push.ts
@@ -27,6 +27,7 @@ interface PushOptions extends SyncOptions {
 
 class RealmPusher extends RealmSyncBase {
   hasError = false;
+  uploadedFiles: string[] = [];
 
   constructor(
     private pushOptions: PushOptions,
@@ -220,6 +221,7 @@ class RealmPusher extends RealmSyncBase {
         for (const { rel, hash } of uploaded) {
           newManifest.files[rel] = hash;
         }
+        this.uploadedFiles.push(...result.succeeded);
       }
     }
 
@@ -362,11 +364,16 @@ export function registerPushCommand(realm: Command): void {
     );
 }
 
-export async function pushCommand(
+export interface PushResult {
+  files: string[];
+  error?: string;
+}
+
+export async function push(
   localDir: string,
   realmUrl: string,
   options: PushCommandOptions,
-): Promise<void> {
+): Promise<PushResult> {
   let authenticator: RealmAuthenticator;
   if (options.authenticator) {
     authenticator = options.authenticator;
@@ -377,15 +384,16 @@ export async function pushCommand(
       profileManager: options.profileManager,
     });
     if (!resolution.ok) {
-      console.error(`Error: ${resolution.error}`);
-      process.exit(1);
+      return { files: [], error: resolution.error };
     }
     authenticator = resolution.authenticator;
   }
 
   if (!(await pathExists(localDir))) {
-    console.error(`Local directory does not exist: ${localDir}`);
-    process.exit(1);
+    return {
+      files: [],
+      error: `Local directory does not exist: ${localDir}`,
+    };
   }
 
   try {
@@ -403,13 +411,31 @@ export async function pushCommand(
     await pusher.sync();
 
     if (pusher.hasError) {
-      console.log('Push did not complete successfully. View logs for details');
-      process.exit(2);
-    } else {
-      console.log('Push completed successfully');
+      return {
+        files: pusher.uploadedFiles.sort(),
+        error:
+          'Push completed with errors. Some files may not have been uploaded.',
+      };
     }
+
+    return { files: pusher.uploadedFiles.sort() };
   } catch (error) {
-    console.error('Push failed:', error);
-    process.exit(1);
+    return {
+      files: [],
+      error: `Push failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export async function pushCommand(
+  localDir: string,
+  realmUrl: string,
+  options: PushCommandOptions,
+): Promise<void> {
+  const result = await push(localDir, realmUrl, options);
+  if (result.error) {
+    console.error(`Error: ${result.error}`);
+    process.exit(result.files.length > 0 ? 2 : 1);
   }
+  console.log('Push completed successfully');
 }
diff --git a/packages/boxel-cli/src/commands/run-command.ts b/packages/boxel-cli/src/commands/run-command.ts
index 8269de7e738..f3943311155 100644
--- a/packages/boxel-cli/src/commands/run-command.ts
+++ b/packages/boxel-cli/src/commands/run-command.ts
@@ -1,5 +1,10 @@
 import type { Command } from 'commander';
-import { getProfileManager, type ProfileManager } from '../lib/profile-manager';
+import {
+  getProfileManager,
+  NO_ACTIVE_PROFILE_ERROR,
+  type ProfileManager,
+} from '../lib/profile-manager';
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
 import { FG_GREEN, FG_RED, FG_CYAN, DIM, RESET } from '../lib/colors';
 import { cliLog } from '../lib/cli-log';
 
@@ -13,6 +18,8 @@ export interface RunCommandOptions {
   input?: Record<string, unknown>;
   json?: boolean;
   profileManager?: ProfileManager;
+  /** Override the realm server URL. Defaults to the active profile's. */
+  realmServerUrl?: string;
 }
 
 interface RunCommandCliOptions {
@@ -27,15 +34,18 @@ export async function runCommand(
   options?: RunCommandOptions,
 ): Promise<RunCommandResult> {
   let pm = options?.profileManager ?? getProfileManager();
-  let active = pm.getActiveProfile();
-  if (!active) {
-    throw new Error(
-      'No active profile. Run `boxel profile add` to create one.',
-    );
+  let realmServerUrl = options?.realmServerUrl;
+  if (!realmServerUrl) {
+    let active = pm.getActiveProfile();
+    if (!active) {
+      return {
+        status: 'error',
+        error: NO_ACTIVE_PROFILE_ERROR,
+      };
+    }
+    realmServerUrl = active.profile.realmServerUrl;
   }
-
-  let realmServerUrl = active.profile.realmServerUrl.replace(/\/$/, '');
-  let url = `${realmServerUrl}/_run-command`;
+  let url = `${ensureTrailingSlash(realmServerUrl)}_run-command`;
 
   let body = {
     data: {
@@ -140,15 +150,7 @@ export function registerRunCommand(program: Command): void {
         }
       }
 
-      let result: RunCommandResult;
-      try {
-        result = await runCommand(commandSpecifier, opts.realm, { input });
-      } catch (err) {
-        console.error(
-          `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
-        );
-        process.exit(1);
-      }
+      let result = await runCommand(commandSpecifier, opts.realm, { input });
 
       if (opts.json) {
         cliLog.output(JSON.stringify(result, null, 2));
diff --git a/packages/boxel-cli/src/lib/boxel-cli-client.ts b/packages/boxel-cli/src/lib/boxel-cli-client.ts
index 0ff19b13938..4c0906d2e03 100644
--- a/packages/boxel-cli/src/lib/boxel-cli-client.ts
+++ b/packages/boxel-cli/src/lib/boxel-cli-client.ts
@@ -19,12 +19,17 @@ import {
   type ReadTranspiledResult,
 } from '../commands/read-transpiled';
 import { write as coreWrite, type WriteResult } from '../commands/file/write';
+import {
+  runCommand as coreRunCommand,
+  type RunCommandResult,
+} from '../commands/run-command';
 import {
   cancelIndexing as coreCancelIndexing,
   type CancelIndexingResult,
 } from '../commands/realm/cancel-indexing';
 import { createRealm as coreCreateRealm } from '../commands/realm/create';
 import { pull as realmPull } from '../commands/realm/pull';
+import { push as realmPush, type PushResult } from '../commands/realm/push';
 import { sync as realmSync, type SyncResult } from '../commands/realm/sync';
 import { waitForReady as coreWaitForReady } from '../commands/realm/wait-for-ready';
 import { getProfileManager, type ProfileManager } from './profile-manager';
@@ -35,6 +40,7 @@ export type {
   ListFilesResult,
   ReadTranspiledResult,
   SyncResult,
+  PushResult,
   SearchResult,
   SearchCommandOptions,
 };
@@ -73,6 +79,15 @@ export interface PullResult {
   error?: string;
 }
 
+export interface PushOptions {
+  /** Delete remote files that don't exist locally (default: false). */
+  delete?: boolean;
+  /** Preview without making changes. */
+  dryRun?: boolean;
+  /** Upload all files, even if unchanged (default: false). */
+  force?: boolean;
+}
+
 export interface SyncOptions {
   /** Resolve conflicts by keeping the local version. */
   preferLocal?: boolean;
@@ -88,13 +103,7 @@ export interface SyncOptions {
 
 export type { DeleteResult };
 export type { WriteResult };
-
-export interface RunCommandResult {
-  status: 'ready' | 'error' | 'unusable';
-  /** Serialized command result (JSON string), or null. */
-  result?: string | null;
-  error?: string | null;
-}
+export type { RunCommandResult };
 
 export type { LintMessage, LintResult };
 
@@ -233,57 +242,11 @@ export class BoxelCLIClient {
     command: string,
     commandInput?: Record<string, unknown>,
   ): Promise<RunCommandResult> {
-    let url = `${ensureTrailingSlash(realmServerUrl)}_run-command`;
-    let body = {
-      data: {
-        type: 'run-command',
-        attributes: {
-          realmURL: realmUrl,
-          command,
-          commandInput: commandInput ?? null,
-        },
-      },
-    };
-
-    let response: Response;
-    try {
-      response = await this.pm.authedRealmServerFetch(url, {
-        method: 'POST',
-        headers: {
-          Accept: MIME.JSONAPI,
-          'Content-Type': MIME.JSONAPI,
-        },
-        body: JSON.stringify(body),
-      });
-    } catch (err) {
-      return {
-        status: 'error',
-        error: `run-command fetch failed: ${err instanceof Error ? err.message : String(err)}`,
-      };
-    }
-
-    if (!response.ok) {
-      return {
-        status: 'error',
-        error: `run-command HTTP ${response.status}: ${await response.text().catch(() => '(no body)')}`,
-      };
-    }
-
-    let json = (await response.json()) as {
-      data?: {
-        attributes?: {
-          status?: string;
-          cardResultString?: string | null;
-          error?: string | null;
-        };
-      };
-    };
-    let attrs = json.data?.attributes;
-    return {
-      status: (attrs?.status as RunCommandResult['status']) ?? 'error',
-      result: attrs?.cardResultString ?? null,
-      error: attrs?.error ?? null,
-    };
+    return coreRunCommand(command, realmUrl, {
+      realmServerUrl,
+      input: commandInput,
+      profileManager: this.pm,
+    });
   }
 
   /**
@@ -430,6 +393,24 @@ export class BoxelCLIClient {
     });
   }
 
+  /**
+   * One-way upload from a local workspace to a realm. Thin wrapper
+   * around the `realm push` command's programmatic `push()` function so
+   * the CLI and programmatic API share one implementation.
+   */
+  async push(
+    realmUrl: string,
+    localDir: string,
+    options?: PushOptions,
+  ): Promise<PushResult> {
+    return realmPush(localDir, realmUrl, {
+      delete: options?.delete,
+      dryRun: options?.dryRun,
+      force: options?.force,
+      profileManager: this.pm,
+    });
+  }
+
   /**
    * Bidirectional sync between a local workspace and a realm. Thin wrapper
    * around the `realm sync` command's programmatic `sync()` function so the
diff --git a/packages/boxel-cli/src/lib/tool-definitions.ts b/packages/boxel-cli/src/lib/tool-definitions.ts
new file mode 100644
index 00000000000..2350a17d44f
--- /dev/null
+++ b/packages/boxel-cli/src/lib/tool-definitions.ts
@@ -0,0 +1,635 @@
+/**
+ * Tool definitions that boxel-cli publishes for factory (and future MCP)
+ * consumption. Each tool wraps a BoxelCLIClient method with name,
+ * description, JSON Schema parameters, and an execute function.
+ *
+ * The factory imports `getToolDefinitions()` and spreads the result into
+ * its FactoryTool[] array — no manual redefinition needed.
+ *
+ * Target-realm files live in the agent's local workspace directory; the
+ * agent edits them with its native filesystem tools (no dedicated
+ * read_file / write_file tool here, since wrapping fs in a tool is strictly
+ * less capable than what the agent can do natively).
+ *
+ * The realm-server-side tools published here take an explicit `realm-url`
+ * argument and hit the realm over HTTP. The factory's
+ * `TARGET_REALM_BYPASS_TOOLS` guard rejects `realm_read_file` /
+ * `realm_write_file` / `realm_delete_file` when `realm-url` matches the
+ * target realm — those are reserved for non-target realms (scratch,
+ * source, catalog, base, etc.) where the agent has no local workspace.
+ */
+
+import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
+
+import type { BoxelCLIClient } from './boxel-cli-client';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface BoxelToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+
+export interface BoxelToolConfig {
+  targetRealmUrl: string;
+  realmServerUrl: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Enforce that a required string argument is present and non-empty. Returns
+ * the trimmed value or throws a clear error that propagates back to the
+ * model as a tool-call result.
+ */
+export function requireStringArg(
+  args: Record<string, unknown>,
+  name: string,
+  toolName: string,
+): string {
+  let raw = args[name];
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    throw new Error(
+      `Tool "${toolName}" requires a non-empty string "${name}" argument; received ${JSON.stringify(raw)}. ` +
+        `Re-send the tool call with every required argument filled in.`,
+    );
+  }
+  return raw.trim();
+}
+
+function resolveRealmUrl(
+  config: BoxelToolConfig,
+  _realm: string | undefined,
+): string {
+  return config.targetRealmUrl;
+}
+
+// ---------------------------------------------------------------------------
+// Realm API tools (parameterized — work on any realm; non-target only for
+// read / write / delete via the factory's TARGET_REALM_BYPASS_TOOLS guard)
+// ---------------------------------------------------------------------------
+
+const NON_TARGET_GUIDANCE =
+  'For target-realm I/O, edit files in the local workspace using your native filesystem tools — this tool is reserved for non-target realms (scratch, source, catalog, base, etc.).';
+
+function buildRealmReadTool(client: BoxelCLIClient): BoxelToolDefinition {
+  return {
+    name: 'realm_read_file',
+    description: `Read a file from a non-target realm as card source. ${NON_TARGET_GUIDANCE} Auth: per-realm JWT.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        'realm-url': {
+          type: 'string',
+          description: 'Absolute URL of the realm to read from.',
+        },
+        path: {
+          type: 'string',
+          description: 'Realm-relative file path.',
+        },
+      },
+      required: ['realm-url', 'path'],
+    },
+    execute: async (args) => {
+      let realmUrl = requireStringArg(args, 'realm-url', 'realm_read_file');
+      let path = requireStringArg(args, 'path', 'realm_read_file');
+      let result = await client.read(realmUrl, path);
+      if (!result.ok) {
+        return { error: result.error, status: result.status };
+      }
+      try {
+        return JSON.parse(result.content ?? '');
+      } catch {
+        return { content: result.content };
+      }
+    },
+  };
+}
+
+function buildRealmWriteTool(client: BoxelCLIClient): BoxelToolDefinition {
+  return {
+    name: 'realm_write_file',
+    description: `Write a file to a non-target realm. The path must include the file extension. ${NON_TARGET_GUIDANCE} Auth: per-realm JWT.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        'realm-url': {
+          type: 'string',
+          description: 'Absolute URL of the realm to write to.',
+        },
+        path: {
+          type: 'string',
+          description:
+            'Realm-relative file path with extension (e.g., "my-card.gts", "Card/1.json").',
+        },
+        content: { type: 'string', description: 'File content.' },
+      },
+      required: ['realm-url', 'path', 'content'],
+    },
+    execute: async (args) => {
+      let realmUrl = requireStringArg(args, 'realm-url', 'realm_write_file');
+      let path = requireStringArg(args, 'path', 'realm_write_file');
+      let content = requireStringArg(args, 'content', 'realm_write_file');
+      return client.write(realmUrl, path, content);
+    },
+  };
+}
+
+function buildRealmDeleteTool(client: BoxelCLIClient): BoxelToolDefinition {
+  return {
+    name: 'realm_delete_file',
+    description: `Delete a file from a non-target realm. ${NON_TARGET_GUIDANCE} Auth: per-realm JWT.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        'realm-url': {
+          type: 'string',
+          description: 'Absolute URL of the realm to delete from.',
+        },
+        path: {
+          type: 'string',
+          description: 'Realm-relative file path to delete.',
+        },
+      },
+      required: ['realm-url', 'path'],
+    },
+    execute: async (args) => {
+      let realmUrl = requireStringArg(args, 'realm-url', 'realm_delete_file');
+      let path = requireStringArg(args, 'path', 'realm_delete_file');
+      return client.delete(realmUrl, path);
+    },
+  };
+}
+
+function buildRealmSearchTool(client: BoxelCLIClient): BoxelToolDefinition {
+  return {
+    name: 'realm_search',
+    description:
+      'Search for cards in a realm using a structured query. Works for both target and non-target realms — realm-index queries have no workspace-fs equivalent. Auth: per-realm JWT.',
+    parameters: {
+      type: 'object',
+      properties: {
+        'realm-url': {
+          type: 'string',
+          description: 'Absolute URL of the realm to search.',
+        },
+        query: {
+          type: ['object', 'string'],
+          description:
+            'Search query (filter, sort, page) — JSON object or JSON-encoded string.',
+        },
+      },
+      required: ['realm-url', 'query'],
+    },
+    execute: async (args) => {
+      let realmUrl = requireStringArg(args, 'realm-url', 'realm_search');
+      let raw = args.query;
+      let query: Record<string, unknown>;
+      if (typeof raw === 'string') {
+        try {
+          query = JSON.parse(raw) as Record<string, unknown>;
+        } catch {
+          return {
+            error:
+              "Invalid JSON for 'query' in realm_search: expected valid JSON.",
+          };
+        }
+      } else if (raw && typeof raw === 'object') {
+        query = raw as Record<string, unknown>;
+      } else {
+        return {
+          error:
+            "Invalid 'query' argument for realm_search: expected a JSON object or JSON-encoded string.",
+        };
+      }
+      let result = await client.search(realmUrl, query);
+      return result.ok
+        ? { data: result.data }
+        : { error: result.error, status: result.status };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Other client wrappers (kept target-bound — they have no non-target use case
+// in the factory loop, or are server-level)
+// ---------------------------------------------------------------------------
+
+function buildFetchTranspiledModuleTool(
+  client: BoxelCLIClient,
+  config: BoxelToolConfig,
+): BoxelToolDefinition {
+  return {
+    name: 'read_transpiled',
+    description:
+      "Debugging tool ONLY for investigating runtime errors in .gts modules you've written. Use when an eval or instantiate validation error reports a line/column number — those line numbers refer to the transpiled output, not your .gts source, so fetching the transpiled output is how you locate the offending source construct. Never use the transpiled output as a reference for how to write code. Do NOT copy its patterns (setComponentTemplate, precompileTemplate, wire-format templates, base64 CSS imports) into source — always write idiomatic Ember / <template>-tag / CardDef source. Editing: only edit the .gts source (the transpiled output is regenerated on the next write). Auth: per-realm JWT.",
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description:
+            'Realm-relative module path. The .gts extension is optional — the realm accepts either form.',
+        },
+        realm: {
+          type: 'string',
+          enum: ['target'],
+          description: 'Which realm to read from (default: target)',
+        },
+      },
+      required: ['path'],
+    },
+    execute: async (args) => {
+      let path = requireStringArg(args, 'path', 'read_transpiled');
+      let realmUrl = resolveRealmUrl(config, args.realm as string | undefined);
+      return client.readTranspiled(realmUrl, path);
+    },
+  };
+}
+
+function buildRunCommandTool(
+  client: BoxelCLIClient,
+  config: BoxelToolConfig,
+): BoxelToolDefinition {
+  return {
+    name: 'run_command',
+    description:
+      'Execute a Boxel host command on the realm server via the prerenderer. ' +
+      'This runs Boxel host commands ONLY — not shell commands, scripts, or Node.js. ' +
+      'Commands must be Boxel host command specifiers in the format ' +
+      '"@cardstack/boxel-host/commands/<name>/default". ' +
+      'Auth: realm server token.',
+    parameters: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          description:
+            'Boxel host command specifier — must be in the format "@cardstack/boxel-host/commands/<name>/default"',
+        },
+        commandInput: {
+          type: 'object',
+          description: 'Optional input for the command',
+        },
+      },
+      required: ['command'],
+    },
+    execute: async (args) => {
+      return client.runCommand(
+        config.realmServerUrl,
+        config.targetRealmUrl,
+        args.command as string,
+        args.commandInput as Record<string, unknown> | undefined,
+      );
+    },
+  };
+}
+
+function buildListFilesTool(
+  client: BoxelCLIClient,
+  config: BoxelToolConfig,
+): BoxelToolDefinition {
+  return {
+    name: 'realm_list_files',
+    description:
+      'List all file paths in a realm. Returns relative paths. Auth: per-realm JWT.',
+    parameters: {
+      type: 'object',
+      properties: {
+        realm: {
+          type: 'string',
+          enum: ['target'],
+          description: 'Which realm to list files from (default: target)',
+        },
+      },
+    },
+    execute: async (args) => {
+      let realmUrl = resolveRealmUrl(config, args.realm as string | undefined);
+      return client.listFiles(realmUrl);
+    },
+  };
+}
+
+function buildLintFileTool(
+  client: BoxelCLIClient,
+  config: BoxelToolConfig,
+): BoxelToolDefinition {
+  return {
+    name: 'realm_lint_file',
+    description:
+      "Lint a single file's source code via the realm's lint endpoint. " +
+      'Returns fixed output and lint messages (errors/warnings). Auth: per-realm JWT.',
+    parameters: {
+      type: 'object',
+      properties: {
+        source: {
+          type: 'string',
+          description: 'The source code to lint',
+        },
+        filename: {
+          type: 'string',
+          description: 'The filename (used to determine lint rules)',
+        },
+        realm: {
+          type: 'string',
+          enum: ['target'],
+          description: 'Which realm to use for linting (default: target)',
+        },
+      },
+      required: ['source', 'filename'],
+    },
+    execute: async (args) => {
+      let source = requireStringArg(args, 'source', 'realm_lint_file');
+      let filename = requireStringArg(args, 'filename', 'realm_lint_file');
+      let realmUrl = resolveRealmUrl(config, args.realm as string | undefined);
+      return client.lint(realmUrl, source, filename);
+    },
+  };
+}
+
+function buildWaitForReadyTool(
+  client: BoxelCLIClient,
+  config: BoxelToolConfig,
+): BoxelToolDefinition {
+  return {
+    name: 'realm_wait_for_ready',
+    description:
+      'Poll a realm until it passes its readiness check. Auth: per-realm JWT.',
+    parameters: {
+      type: 'object',
+      properties: {
+        realm: {
+          type: 'string',
+          enum: ['target'],
+          description: 'Which realm to check (default: target)',
+        },
+        timeoutMs: {
+          type: 'number',
+          description: 'Timeout in milliseconds (default: 30000)',
+        },
+      },
+    },
+    execute: async (args) => {
+      let realmUrl = resolveRealmUrl(config, args.realm as string | undefined);
+      let timeoutMs =
+        typeof args.timeoutMs === 'number' ? args.timeoutMs : undefined;
+      return client.waitForReady(realmUrl, timeoutMs);
+    },
+  };
+}
+
+function buildCancelIndexingTool(
+  client: BoxelCLIClient,
+  config: BoxelToolConfig,
+): BoxelToolDefinition {
+  return {
+    name: 'realm_cancel_indexing',
+    description:
+      'Cancel all running and pending indexing jobs for a realm. Auth: per-realm JWT.',
+    parameters: {
+      type: 'object',
+      properties: {
+        realm: {
+          type: 'string',
+          enum: ['target'],
+          description: 'Which realm to cancel indexing for (default: target)',
+        },
+      },
+    },
+    execute: async (args) => {
+      let realmUrl = resolveRealmUrl(config, args.realm as string | undefined);
+      return client.cancelAllIndexingJobs(realmUrl);
+    },
+  };
+}
+
+function buildRealmCreateTool(client: BoxelCLIClient): BoxelToolDefinition {
+  return {
+    name: 'create_realm',
+    description:
+      "Create a new realm on the active profile's realm server. The supplied `realm-server-url` is validated against the active profile to prevent accidental cross-server creates. Auth: realm server token.",
+    parameters: {
+      type: 'object',
+      properties: {
+        'realm-server-url': {
+          type: 'string',
+          description:
+            'Realm server base URL. Must match the active Boxel profile.',
+        },
+        name: {
+          type: 'string',
+          description: 'Display name for the new realm.',
+        },
+        endpoint: {
+          type: 'string',
+          description:
+            'URL path segment for the new realm (e.g. "user/my-realm").',
+        },
+        iconURL: {
+          type: 'string',
+          description:
+            'Optional icon URL. Defaults to a letter-based icon derived from the realm name.',
+        },
+        backgroundURL: {
+          type: 'string',
+          description:
+            'Optional background image URL. Defaults to a random background image.',
+        },
+      },
+      required: ['realm-server-url', 'name', 'endpoint'],
+    },
+    execute: async (args) => {
+      let requestedServerUrl = ensureTrailingSlash(
+        requireStringArg(args, 'realm-server-url', 'create_realm'),
+      );
+      let displayName = requireStringArg(args, 'name', 'create_realm');
+      let realmName = requireStringArg(args, 'endpoint', 'create_realm');
+      let active = client.getActiveProfile();
+      if (
+        active &&
+        ensureTrailingSlash(active.realmServerUrl) !== requestedServerUrl
+      ) {
+        return {
+          error: `create_realm cannot target "${requestedServerUrl}": active Boxel profile realm server is "${ensureTrailingSlash(active.realmServerUrl)}".`,
+        };
+      }
+      let result = await client.createRealm({
+        realmName,
+        displayName,
+        iconURL: args.iconURL as string | undefined,
+        backgroundURL: args.backgroundURL as string | undefined,
+      });
+      return { data: { id: result.realmUrl } };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Workspace ⇄ realm sync tools (parameterized — operate on any realm)
+// ---------------------------------------------------------------------------
+
+function buildRealmSyncTool(client: BoxelCLIClient): BoxelToolDefinition {
+  return {
+    name: 'realm_sync',
+    description:
+      'Bidirectional sync between a local workspace directory and a realm. Pushes local changes, pulls remote changes, resolves conflicts via the chosen strategy. Auth: per-realm JWT.',
+    parameters: {
+      type: 'object',
+      properties: {
+        'realm-url': {
+          type: 'string',
+          description: 'Absolute URL of the realm to sync with.',
+        },
+        'local-dir': {
+          type: 'string',
+          description: 'Local workspace directory path.',
+        },
+        prefer: {
+          type: 'string',
+          enum: ['local', 'remote', 'newest'],
+          description:
+            'Conflict-resolution strategy when both sides have changed (default: interactive prompt).',
+        },
+        delete: {
+          type: 'boolean',
+          description:
+            'Propagate deletions in both directions (default: false).',
+        },
+        'dry-run': {
+          type: 'boolean',
+          description: 'Preview only — make no changes (default: false).',
+        },
+      },
+      required: ['realm-url', 'local-dir'],
+    },
+    execute: async (args) => {
+      let realmUrl = requireStringArg(args, 'realm-url', 'realm_sync');
+      let localDir = requireStringArg(args, 'local-dir', 'realm_sync');
+      let prefer = args.prefer as string | undefined;
+      return client.sync(realmUrl, localDir, {
+        preferLocal: prefer === 'local',
+        preferRemote: prefer === 'remote',
+        preferNewest: prefer === 'newest',
+        delete: args.delete as boolean | undefined,
+        dryRun: args['dry-run'] as boolean | undefined,
+      });
+    },
+  };
+}
+
+function buildRealmPushTool(client: BoxelCLIClient): BoxelToolDefinition {
+  return {
+    name: 'realm_push',
+    description:
+      'One-way upload from a local workspace directory to a realm. Use when you know local should overwrite remote. Auth: per-realm JWT.',
+    parameters: {
+      type: 'object',
+      properties: {
+        'realm-url': {
+          type: 'string',
+          description: 'Absolute URL of the target realm.',
+        },
+        'local-dir': {
+          type: 'string',
+          description: 'Local directory containing files to upload.',
+        },
+        delete: {
+          type: 'boolean',
+          description:
+            'Delete remote files that do not exist locally (default: false).',
+        },
+        'dry-run': {
+          type: 'boolean',
+          description: 'Preview only — make no changes (default: false).',
+        },
+        force: {
+          type: 'boolean',
+          description: 'Upload all files, even if unchanged (default: false).',
+        },
+      },
+      required: ['realm-url', 'local-dir'],
+    },
+    execute: async (args) => {
+      let realmUrl = requireStringArg(args, 'realm-url', 'realm_push');
+      let localDir = requireStringArg(args, 'local-dir', 'realm_push');
+      return client.push(realmUrl, localDir, {
+        delete: args.delete as boolean | undefined,
+        dryRun: args['dry-run'] as boolean | undefined,
+        force: args.force as boolean | undefined,
+      });
+    },
+  };
+}
+
+function buildRealmPullTool(client: BoxelCLIClient): BoxelToolDefinition {
+  return {
+    name: 'realm_pull',
+    description:
+      'One-way download from a realm to a local workspace directory. Use when you know remote should overwrite local. Auth: per-realm JWT.',
+    parameters: {
+      type: 'object',
+      properties: {
+        'realm-url': {
+          type: 'string',
+          description: 'Absolute URL of the source realm.',
+        },
+        'local-dir': {
+          type: 'string',
+          description: 'Local directory to download into.',
+        },
+        delete: {
+          type: 'boolean',
+          description:
+            'Delete local files that do not exist on the realm (default: false).',
+        },
+      },
+      required: ['realm-url', 'local-dir'],
+    },
+    execute: async (args) => {
+      let realmUrl = requireStringArg(args, 'realm-url', 'realm_pull');
+      let localDir = requireStringArg(args, 'local-dir', 'realm_pull');
+      return client.pull(realmUrl, localDir, {
+        delete: args.delete as boolean | undefined,
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build tool definitions for all boxel-cli operations. The factory (or any
+ * other consumer) calls this once and spreads the result into its tool array.
+ *
+ * Each tool's execute function is pre-bound to the provided client and config,
+ * so the consumer never needs to know about realm URLs or auth.
+ */
+export function getToolDefinitions(
+  client: BoxelCLIClient,
+  config: BoxelToolConfig,
+): BoxelToolDefinition[] {
+  return [
+    buildRealmReadTool(client),
+    buildRealmWriteTool(client),
+    buildRealmDeleteTool(client),
+    buildRealmSearchTool(client),
+    buildRealmCreateTool(client),
+    buildRealmSyncTool(client),
+    buildRealmPushTool(client),
+    buildRealmPullTool(client),
+    buildFetchTranspiledModuleTool(client, config),
+    buildRunCommandTool(client, config),
+    buildListFilesTool(client, config),
+    buildLintFileTool(client, config),
+    buildWaitForReadyTool(client, config),
+    buildCancelIndexingTool(client, config),
+  ];
+}
diff --git a/packages/boxel-cli/tests/lib/tool-definitions.test.ts b/packages/boxel-cli/tests/lib/tool-definitions.test.ts
new file mode 100644
index 00000000000..98e1a1af787
--- /dev/null
+++ b/packages/boxel-cli/tests/lib/tool-definitions.test.ts
@@ -0,0 +1,397 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  getToolDefinitions,
+  requireStringArg,
+  type BoxelToolConfig,
+} from '../../src/lib/tool-definitions';
+import type { BoxelCLIClient } from '../../src/lib/boxel-cli-client';
+
+const TEST_CONFIG: BoxelToolConfig = {
+  targetRealmUrl: 'https://realms.example.test/user/target/',
+  realmServerUrl: 'https://realms.example.test/',
+};
+
+function createMockClient(): BoxelCLIClient {
+  return {
+    read: vi.fn().mockResolvedValue({ ok: true, document: { data: {} } }),
+    write: vi.fn().mockResolvedValue({ ok: true }),
+    delete: vi.fn().mockResolvedValue({ ok: true }),
+    readTranspiled: vi
+      .fn()
+      .mockResolvedValue({ ok: true, content: 'compiled' }),
+    search: vi.fn().mockResolvedValue({ ok: true, data: [] }),
+    runCommand: vi.fn().mockResolvedValue({ status: 'ready', result: null }),
+    listFiles: vi.fn().mockResolvedValue({ filenames: ['a.gts', 'b.json'] }),
+    lint: vi.fn().mockResolvedValue({ fixed: false, output: '', messages: [] }),
+    waitForReady: vi.fn().mockResolvedValue({ ready: true }),
+    cancelAllIndexingJobs: vi.fn().mockResolvedValue({ ok: true }),
+    createRealm: vi.fn().mockResolvedValue({
+      realmUrl: 'https://realms.example.test/user/new/',
+      created: true,
+    }),
+    sync: vi.fn().mockResolvedValue({ pushedFiles: [], pulledFiles: [] }),
+    push: vi.fn().mockResolvedValue({ files: [] }),
+    pull: vi.fn().mockResolvedValue({ files: [] }),
+    getActiveProfile: vi.fn().mockReturnValue(null),
+  } as unknown as BoxelCLIClient;
+}
+
+describe('getToolDefinitions', () => {
+  it('returns expected tool names', () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let names = tools.map((t) => t.name);
+
+    expect(names).toContain('realm_read_file');
+    expect(names).toContain('realm_write_file');
+    expect(names).toContain('realm_delete_file');
+    expect(names).toContain('realm_search');
+    expect(names).toContain('create_realm');
+    expect(names).toContain('realm_sync');
+    expect(names).toContain('realm_push');
+    expect(names).toContain('realm_pull');
+    expect(names).toContain('read_transpiled');
+    expect(names).toContain('run_command');
+    expect(names).toContain('realm_list_files');
+    expect(names).toContain('realm_lint_file');
+    expect(names).toContain('realm_wait_for_ready');
+    expect(names).toContain('realm_cancel_indexing');
+    expect(tools.length).toBe(14);
+  });
+
+  it('realm_sync.execute calls client.sync with options mapped from prefer', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_sync')!;
+
+    await tool.execute({
+      'realm-url': 'https://realms.example.test/user/scratch/',
+      'local-dir': './workspace',
+      prefer: 'local',
+      delete: true,
+    });
+
+    expect(client.sync).toHaveBeenCalledWith(
+      'https://realms.example.test/user/scratch/',
+      './workspace',
+      {
+        preferLocal: true,
+        preferRemote: false,
+        preferNewest: false,
+        delete: true,
+        dryRun: undefined,
+      },
+    );
+  });
+
+  it('realm_push.execute calls client.push with delete/force/dry-run', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_push')!;
+
+    await tool.execute({
+      'realm-url': 'https://realms.example.test/user/scratch/',
+      'local-dir': './workspace',
+      delete: true,
+      force: true,
+      'dry-run': false,
+    });
+
+    expect(client.push).toHaveBeenCalledWith(
+      'https://realms.example.test/user/scratch/',
+      './workspace',
+      { delete: true, dryRun: false, force: true },
+    );
+  });
+
+  it('realm_pull.execute calls client.pull with delete option', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_pull')!;
+
+    await tool.execute({
+      'realm-url': 'https://realms.example.test/user/scratch/',
+      'local-dir': './workspace',
+      delete: true,
+    });
+
+    expect(client.pull).toHaveBeenCalledWith(
+      'https://realms.example.test/user/scratch/',
+      './workspace',
+      { delete: true },
+    );
+  });
+
+  it('each tool has name, description, parameters, and execute', () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+
+    for (let tool of tools) {
+      expect(typeof tool.name).toBe('string');
+      expect(tool.name.length).toBeGreaterThan(0);
+      expect(typeof tool.description).toBe('string');
+      expect(tool.description.length).toBeGreaterThan(0);
+      expect(typeof tool.parameters).toBe('object');
+      expect(typeof tool.execute).toBe('function');
+    }
+  });
+
+  it('realm_write_file.execute calls client.write with the supplied realm-url', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_write_file')!;
+
+    let scratchRealmUrl = 'https://realms.example.test/user/scratch/';
+    await tool.execute({
+      'realm-url': scratchRealmUrl,
+      path: 'card.gts',
+      content: 'export class A {}',
+    });
+
+    expect(client.write).toHaveBeenCalledWith(
+      scratchRealmUrl,
+      'card.gts',
+      'export class A {}',
+    );
+  });
+
+  it('realm_read_file.execute calls client.read with the supplied realm-url', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_read_file')!;
+
+    let scratchRealmUrl = 'https://realms.example.test/user/scratch/';
+    await tool.execute({ 'realm-url': scratchRealmUrl, path: 'Card/1.json' });
+
+    expect(client.read).toHaveBeenCalledWith(scratchRealmUrl, 'Card/1.json');
+  });
+
+  it('realm_delete_file.execute calls client.delete with the supplied realm-url', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_delete_file')!;
+
+    let scratchRealmUrl = 'https://realms.example.test/user/scratch/';
+    await tool.execute({ 'realm-url': scratchRealmUrl, path: 'old.json' });
+
+    expect(client.delete).toHaveBeenCalledWith(scratchRealmUrl, 'old.json');
+  });
+
+  it('realm_search.execute calls client.search and shapes response', async () => {
+    let client = createMockClient();
+    (client.search as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      data: [{ id: '1' }],
+    });
+
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_search')!;
+
+    let scratchRealmUrl = 'https://realms.example.test/user/scratch/';
+    let result = await tool.execute({
+      'realm-url': scratchRealmUrl,
+      query: { filter: { type: { name: 'Card' } } },
+    });
+
+    expect(client.search).toHaveBeenCalledWith(scratchRealmUrl, {
+      filter: { type: { name: 'Card' } },
+    });
+    expect(result).toEqual({ data: [{ id: '1' }] });
+  });
+
+  it('realm_search.execute returns error on failure', async () => {
+    let client = createMockClient();
+    (client.search as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: false,
+      error: 'Not found',
+    });
+
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_search')!;
+
+    let result = await tool.execute({
+      'realm-url': 'https://realms.example.test/user/scratch/',
+      query: {},
+    });
+
+    expect(result).toEqual({ error: 'Not found' });
+  });
+
+  it('realm_read_file.execute throws when realm-url is missing', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_read_file')!;
+
+    await expect(tool.execute({ path: 'Card/1.json' })).rejects.toThrow(
+      'requires a non-empty string "realm-url"',
+    );
+    expect(client.read).not.toHaveBeenCalled();
+  });
+
+  it('run_command.execute passes realmServerUrl and targetRealmUrl', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'run_command')!;
+
+    await tool.execute({
+      command: '@cardstack/boxel-host/commands/get-card-type-schema/default',
+      commandInput: { cardURL: 'http://example.test/Card' },
+    });
+
+    expect(client.runCommand).toHaveBeenCalledWith(
+      TEST_CONFIG.realmServerUrl,
+      TEST_CONFIG.targetRealmUrl,
+      '@cardstack/boxel-host/commands/get-card-type-schema/default',
+      { cardURL: 'http://example.test/Card' },
+    );
+  });
+
+  it('realm_list_files.execute calls client.listFiles', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_list_files')!;
+
+    let result = await tool.execute({});
+
+    expect(client.listFiles).toHaveBeenCalledWith(TEST_CONFIG.targetRealmUrl);
+    expect(result).toEqual({ filenames: ['a.gts', 'b.json'] });
+  });
+
+  it('realm_lint_file.execute calls client.lint with source and filename', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_lint_file')!;
+
+    await tool.execute({ source: 'let x = 1;', filename: 'test.gts' });
+
+    expect(client.lint).toHaveBeenCalledWith(
+      TEST_CONFIG.targetRealmUrl,
+      'let x = 1;',
+      'test.gts',
+    );
+  });
+
+  it('realm_wait_for_ready.execute calls client.waitForReady', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_wait_for_ready')!;
+
+    let result = await tool.execute({ timeoutMs: 5000 });
+
+    expect(client.waitForReady).toHaveBeenCalledWith(
+      TEST_CONFIG.targetRealmUrl,
+      5000,
+    );
+    expect(result).toEqual({ ready: true });
+  });
+
+  it('realm_cancel_indexing.execute calls client.cancelAllIndexingJobs', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'realm_cancel_indexing')!;
+
+    let result = await tool.execute({});
+
+    expect(client.cancelAllIndexingJobs).toHaveBeenCalledWith(
+      TEST_CONFIG.targetRealmUrl,
+    );
+    expect(result).toEqual({ ok: true });
+  });
+
+  it('create_realm.execute maps endpoint/name to realmName/displayName', async () => {
+    let client = createMockClient();
+    (client.getActiveProfile as ReturnType<typeof vi.fn>).mockReturnValue({
+      matrixId: '@test:realms.example.test',
+      realmServerUrl: TEST_CONFIG.realmServerUrl,
+    });
+
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'create_realm')!;
+
+    await tool.execute({
+      'realm-server-url': TEST_CONFIG.realmServerUrl,
+      endpoint: 'user/widgets',
+      name: 'Widgets',
+      iconURL: 'https://icons.test/w.png',
+      backgroundURL: 'https://bgs.test/w.jpg',
+    });
+
+    expect(client.createRealm).toHaveBeenCalledWith({
+      realmName: 'user/widgets',
+      displayName: 'Widgets',
+      iconURL: 'https://icons.test/w.png',
+      backgroundURL: 'https://bgs.test/w.jpg',
+    });
+  });
+
+  it('create_realm.execute rejects mismatched realm-server-url against active profile', async () => {
+    let client = createMockClient();
+    (client.getActiveProfile as ReturnType<typeof vi.fn>).mockReturnValue({
+      matrixId: '@test:realms.example.test',
+      realmServerUrl: 'https://prod.example.test/',
+    });
+
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'create_realm')!;
+
+    let result = (await tool.execute({
+      'realm-server-url': 'https://staging.example.test/',
+      endpoint: 'user/widgets',
+      name: 'Widgets',
+    })) as { error?: string };
+
+    expect(result.error).toMatch(/cannot target/);
+    expect(client.createRealm).not.toHaveBeenCalled();
+  });
+
+  it('create_realm.execute throws when realm-server-url is missing', async () => {
+    let client = createMockClient();
+    let tools = getToolDefinitions(client, TEST_CONFIG);
+    let tool = tools.find((t) => t.name === 'create_realm')!;
+
+    await expect(
+      tool.execute({ endpoint: 'user/x', name: 'X' }),
+    ).rejects.toThrow('requires a non-empty string "realm-server-url"');
+    expect(client.createRealm).not.toHaveBeenCalled();
+  });
+});
+
+describe('requireStringArg', () => {
+  it('returns trimmed value for valid string', () => {
+    let result = requireStringArg({ path: 'hello.gts' }, 'path', 'test_tool');
+    expect(result).toBe('hello.gts');
+  });
+
+  it('trims surrounding whitespace from the returned value', () => {
+    let result = requireStringArg(
+      { 'realm-url': '  https://realms.example.test/user/x/  ' },
+      'realm-url',
+      'test_tool',
+    );
+    expect(result).toBe('https://realms.example.test/user/x/');
+  });
+
+  it('throws for missing arg', () => {
+    expect(() => requireStringArg({}, 'path', 'test_tool')).toThrow(
+      'requires a non-empty string "path"',
+    );
+  });
+
+  it('throws for empty string', () => {
+    expect(() => requireStringArg({ path: '' }, 'path', 'test_tool')).toThrow(
+      'requires a non-empty string "path"',
+    );
+  });
+
+  it('throws for non-string value', () => {
+    expect(() => requireStringArg({ path: 42 }, 'path', 'test_tool')).toThrow(
+      'requires a non-empty string "path"',
+    );
+  });
+
+  it('throws for undefined', () => {
+    expect(() =>
+      requireStringArg({ path: undefined }, 'path', 'test_tool'),
+    ).toThrow('requires a non-empty string "path"');
+  });
+});
diff --git a/packages/software-factory/.agents/skills/boxel-development/references/dev-qunit-testing.md b/packages/software-factory/.agents/skills/boxel-development/references/dev-qunit-testing.md
index 72671ed3fd9..709327ffca3 100644
--- a/packages/software-factory/.agents/skills/boxel-development/references/dev-qunit-testing.md
+++ b/packages/software-factory/.agents/skills/boxel-development/references/dev-qunit-testing.md
@@ -134,7 +134,7 @@ Add `data-test-*` attributes to card templates for stable test selectors:
 
 When tests fail, the orchestrator feeds test failure details back to the agent. For more detail:
 
-- **TestRun cards** live in the target realm's `Validations/` folder with a `test_` prefix (e.g., `Validations/test_issue-slug-1.json`). To find all test runs, search by the TestRun card type in the target realm. Each TestRun has a `sequenceNumber` that increases with each iteration. Use `read_file` on a specific TestRun for full details.
+- **TestRun cards** live in the target realm's `Validations/` folder with a `test_` prefix (e.g., `Validations/test_issue-slug-1.json`). To find all test runs, search by the TestRun card type in the target realm. Each TestRun has a `sequenceNumber` that increases with each iteration. Read the file directly from the workspace dir for full details.
 
 ## Rules
 
diff --git a/packages/software-factory/.agents/skills/boxel-development/references/dev-spec-usage.md b/packages/software-factory/.agents/skills/boxel-development/references/dev-spec-usage.md
index 4f19b8ac335..8f6bc9fb393 100644
--- a/packages/software-factory/.agents/skills/boxel-development/references/dev-spec-usage.md
+++ b/packages/software-factory/.agents/skills/boxel-development/references/dev-spec-usage.md
@@ -18,7 +18,7 @@ Key concepts:
 
 Create at least one sample instance with realistic data for each top-level card. Sample instances serve as both catalog examples and test fixtures.
 
-Place sample instances in a folder named after the card type (e.g., `StickyNote/welcome-note.json`). Use `write_file` to create them. The `linkedExamples` relationship in the Spec card points to these using a relative path (e.g., `../StickyNote/welcome-note`).
+Place sample instances in a folder named after the card type (e.g., `StickyNote/welcome-note.json`) — for the target realm, create them with your native filesystem tools in the workspace dir. The `linkedExamples` relationship in the Spec card points to these using a relative path (e.g., `../StickyNote/welcome-note`).
 
 ---
 
diff --git a/packages/software-factory/.agents/skills/boxel-repair/SKILL.md b/packages/software-factory/.agents/skills/boxel-repair/SKILL.md
index a47dff30f2a..dbf820fe992 100644
--- a/packages/software-factory/.agents/skills/boxel-repair/SKILL.md
+++ b/packages/software-factory/.agents/skills/boxel-repair/SKILL.md
@@ -3,7 +3,7 @@ name: boxel-repair
 description: Use when a Boxel workspace has broken realm metadata, missing icons or backgrounds, bad `index.json` or `cards-grid.json` links, or stale Matrix realm metadata that needs `boxel repair-realm` or `boxel repair-realms`.
 ---
 
-> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent's tool registry does not include boxel-cli tools — all realm I/O uses `write_file`, `read_file`, and `search_realm` tools via the realm HTTP API.
+> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent has its own tools for realm operations. Target-realm files are pre-synced into a local workspace directory and the orchestration loop handles target-realm sync between turns, so for target-realm files the agent reads/edits with its native filesystem tools (`Read` / `Write` / `Edit`).
 
 # Boxel Repair
 
diff --git a/packages/software-factory/.agents/skills/boxel-restore/SKILL.md b/packages/software-factory/.agents/skills/boxel-restore/SKILL.md
index 0e427fce6e7..fb3613197bd 100644
--- a/packages/software-factory/.agents/skills/boxel-restore/SKILL.md
+++ b/packages/software-factory/.agents/skills/boxel-restore/SKILL.md
@@ -3,7 +3,7 @@ name: boxel-restore
 description: Use when restoring a Boxel workspace to a previous checkpoint and syncing deletions back to the server safely, including stopping watch first and running `boxel sync . --prefer-local` after restore.
 ---
 
-> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent's tool registry does not include boxel-cli tools — all realm I/O uses `write_file`, `read_file`, and `search_realm` tools via the realm HTTP API.
+> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent has its own tools for realm operations. Target-realm files are pre-synced into a local workspace directory and the orchestration loop handles target-realm sync between turns, so for target-realm files the agent reads/edits with its native filesystem tools (`Read` / `Write` / `Edit`).
 
 # Boxel Restore
 
diff --git a/packages/software-factory/.agents/skills/boxel-setup/SKILL.md b/packages/software-factory/.agents/skills/boxel-setup/SKILL.md
index aeb72d9211d..221ce3b4288 100644
--- a/packages/software-factory/.agents/skills/boxel-setup/SKILL.md
+++ b/packages/software-factory/.agents/skills/boxel-setup/SKILL.md
@@ -3,7 +3,7 @@ name: boxel-setup
 description: Use for Boxel CLI onboarding, profile setup, verifying login, listing workspaces, switching profiles, or helping a new user perform their first sync.
 ---
 
-> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent's tool registry does not include boxel-cli tools — all realm I/O uses `write_file`, `read_file`, and `search_realm` tools via the realm HTTP API.
+> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent has its own tools for realm operations. Target-realm files are pre-synced into a local workspace directory and the orchestration loop handles target-realm sync between turns, so for target-realm files the agent reads/edits with its native filesystem tools (`Read` / `Write` / `Edit`).
 
 # Boxel Setup
 
diff --git a/packages/software-factory/.agents/skills/boxel-sync/SKILL.md b/packages/software-factory/.agents/skills/boxel-sync/SKILL.md
index c54845695e9..d34510153e0 100644
--- a/packages/software-factory/.agents/skills/boxel-sync/SKILL.md
+++ b/packages/software-factory/.agents/skills/boxel-sync/SKILL.md
@@ -3,7 +3,7 @@ name: boxel-sync
 description: Use when deciding how to sync a Boxel workspace after local edits, server changes, or a restore, including choosing between interactive sync, `--prefer-local`, `--prefer-remote`, or `--prefer-newest`.
 ---
 
-> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent's tool registry does not include boxel-cli tools — all realm I/O uses `write_file`, `read_file`, and `search_realm` tools via the realm HTTP API.
+> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent has its own tools for realm operations. Target-realm files are pre-synced into a local workspace directory and the orchestration loop handles target-realm sync between turns, so for target-realm files the agent reads/edits with its native filesystem tools (`Read` / `Write` / `Edit`).
 
 # Boxel Sync
 
diff --git a/packages/software-factory/.agents/skills/boxel-track/SKILL.md b/packages/software-factory/.agents/skills/boxel-track/SKILL.md
index a47d8df6af7..71e8d8e7954 100644
--- a/packages/software-factory/.agents/skills/boxel-track/SKILL.md
+++ b/packages/software-factory/.agents/skills/boxel-track/SKILL.md
@@ -3,7 +3,7 @@ name: boxel-track
 description: Use when starting or explaining `boxel track` for local file watching, automatic checkpoints, or optional real-time push with `--push` during Boxel development.
 ---
 
-> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent's tool registry does not include boxel-cli tools — all realm I/O uses `write_file`, `read_file`, and `search_realm` tools via the realm HTTP API.
+> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent has its own tools for realm operations. Target-realm files are pre-synced into a local workspace directory and the orchestration loop handles target-realm sync between turns, so for target-realm files the agent reads/edits with its native filesystem tools (`Read` / `Write` / `Edit`).
 
 # Boxel Track
 
diff --git a/packages/software-factory/.agents/skills/boxel-watch/SKILL.md b/packages/software-factory/.agents/skills/boxel-watch/SKILL.md
index 5886bb8552a..84be8c79816 100644
--- a/packages/software-factory/.agents/skills/boxel-watch/SKILL.md
+++ b/packages/software-factory/.agents/skills/boxel-watch/SKILL.md
@@ -3,7 +3,7 @@ name: boxel-watch
 description: Use when starting or choosing settings for `boxel watch` to monitor remote Boxel changes, including active-development, quick-feedback, and background-monitoring intervals.
 ---
 
-> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent's tool registry does not include boxel-cli tools — all realm I/O uses `write_file`, `read_file`, and `search_realm` tools via the realm HTTP API.
+> **Factory agent note:** This skill is for human Claude Code sessions only. The factory agent has its own tools for realm operations. Target-realm files are pre-synced into a local workspace directory and the orchestration loop handles target-realm sync between turns, so for target-realm files the agent reads/edits with its native filesystem tools (`Read` / `Write` / `Edit`).
 
 # Boxel Watch
 
diff --git a/packages/software-factory/.agents/skills/software-factory-bootstrap/SKILL.md b/packages/software-factory/.agents/skills/software-factory-bootstrap/SKILL.md
index 6f2c165b108..6f76d171801 100644
--- a/packages/software-factory/.agents/skills/software-factory-bootstrap/SKILL.md
+++ b/packages/software-factory/.agents/skills/software-factory-bootstrap/SKILL.md
@@ -110,7 +110,7 @@ these relationships, the agent would have no project scope or brief content.
 
 ## JSON:API Document Format
 
-Every card written via `write_file` must be a JSON:API document:
+Every card file you write into the workspace must be a JSON:API document:
 
 ```json
 {
diff --git a/packages/software-factory/.agents/skills/software-factory-operations/SKILL.md b/packages/software-factory/.agents/skills/software-factory-operations/SKILL.md
index b08bbcfa689..424a1360c4b 100644
--- a/packages/software-factory/.agents/skills/software-factory-operations/SKILL.md
+++ b/packages/software-factory/.agents/skills/software-factory-operations/SKILL.md
@@ -5,7 +5,7 @@ description: Use when implementing cards in a target realm through the factory e
 
 # Software Factory Operations
 
-Use this skill when operating inside the factory execution loop. The factory agent communicates with realms exclusively through **executable tool functions** — not local filesystem writes or boxel CLI commands.
+Use this skill when operating inside the factory execution loop. The factory agent edits **target-realm files in a local workspace directory** using its native filesystem tools (`Read` / `Write` / `Edit` / shell), and uses **executable tool functions** for everything else (search, lint, validation, project state, control flow). Target-realm files are pre-synced into the workspace and the loop handles target-realm sync between your turns. For other realm operations, use the available tools.
 
 ## Realm Roles
 
@@ -20,13 +20,14 @@ The agent has these tools during the execution loop. Use them by name — they a
 
 ### Reading and Searching
 
-- `read_file({ path, realm? })` — Read a file from the target realm. Use before modifying anything.
-- `fetch_transpiled_module({ path, realm? })` — Fetch the compiled JavaScript output of a `.gts` module. Use when an eval/instantiate error reports a line/column — those numbers reference the transpiled output, not your source.
-- `search_realm({ query, realm? })` — Search for cards using a structured query object (filter, sort, page). Use to check for existing cards, find duplicates, inspect project state.
+- **Reading target-realm files** — Use your native `Read` tool (or shell `cat` / `head` / `grep`) on files in the workspace directory. There is no `read_file` tool; the workspace dir is just a normal local directory.
+- `read_transpiled({ path, realm? })` — Fetch the compiled JavaScript output of a `.gts` module. Use when an eval/instantiate error reports a line/column — those numbers reference the transpiled output, not your source.
+- `realm_search({ 'realm-url', query })` — Search for cards using a structured query object (filter, sort, page). `realm-url` is required — pass the target realm URL when searching the realm you're implementing against. Use to check for existing cards, find duplicates, inspect project state.
 
 ### Writing Files
 
-- `write_file({ path, content, realm? })` — Write a file to the target realm. Path must include extension (`.gts`, `.json`, `.test.gts`).
+- **Writing target-realm files** — Use your native `Write` / `Edit` tools (or shell redirects) on files in the workspace directory. Path is whatever fits inside the workspace dir; the loop syncs the workspace to the realm between iterations. Always write clean idiomatic source — never compiled JSON blocks, base64-encoded content, or wire-format template arrays.
+- For files in non-target realms (scratch, source, catalog, etc.) the agent has no local workspace — use `realm_write_file({ 'realm-url', path, content })` or `realm_read_file({ 'realm-url', path })` instead.
 
 ### Updating Project State
 
@@ -63,8 +64,8 @@ All five tools are safe to call repeatedly mid-turn; none of them write a realm
 - `run_lint({ path? })` — Run ESLint + Prettier (with `@cardstack/boxel` rules) and return an in-memory `RunLintResult` with `status`, `filesChecked`, `filesWithErrors`, `errorCount`, `warningCount`, `durationMs`, `lintableFiles`, and per-violation `{ rule, file, line, column, message, severity }`. Without `path`, lints every `.gts` / `.gjs` / `.ts` / `.js` file in the target realm. With `path` (realm-relative file path), lints **only that one file** — prefer this right after writing or editing a single file.
 - `run_tests()` — Run the realm's QUnit suite and receive an in-memory result object `{ status, passedCount, failedCount, skippedCount, durationMs, testFiles, failures, errorMessage? }`. Use it when you want feedback before signalling done.
 - `run_parse({ path? })` — Parse and type-check files in the target realm and return an in-memory `RunParseResult` with `status`, `filesChecked`, `filesWithErrors`, `errorCount`, `durationMs`, `parseableFiles`, and per-error `{ file, line, column, message }`. Without `path`, runs glint (ember-tsc) over every `.gts` / `.gjs` / `.ts` file in the realm AND validates every `.json` file listed as a Spec `linkedExample` (same discovery as the parse validation step). With `path` (realm-relative file path), parses **only that one file** — `.gts` / `.gjs` / `.ts` runs through glint; `.json` is parsed and checked for card document structure. The extension is required; `parseableFiles` entries are always returned in the `.json` / `.gts` / `.gjs` / `.ts` form, so you can feed any of them straight back into `path`. Prefer the single-file form right after writing or editing one file.
-- `run_evaluate({ path? })` — Evaluate ESM modules (`.gts` / `.gjs` / `.ts` / `.js`) in the target realm via the prerenderer sandbox and return a `RunEvaluateResult` (status, module counts, per-failure `{ path, error, stackTrace? }`). Without `path`, evaluates every non-test evaluable module. With `path`, evaluates only that single realm-relative file — handy for a quick self-check right after writing one module. Test files (`*.test.*`) are rejected — the test runner validates those. When a failure reports a line/column, those numbers refer to the transpiled module — pair with `fetch_transpiled_module` to locate the offending source construct, then fix the `.gts` source (never copy transpiled patterns back into source).
-- `run_instantiate({ path? })` — Instantiate card example instances in the target realm via the prerenderer sandbox and return a `RunInstantiateResult` (status, instance counts, per-failure `{ path, cardName, error, stackTrace? }`). Without `path`, searches the realm for Spec cards and instantiates every `linkedExample` on every card/app Spec; specs with no `linkedExamples` still get a bare instantiation to exercise the card class. With `path`, instantiates only that single realm-relative `.json` example file — its `meta.adoptsFrom` supplies the module + card name, and spec discovery is skipped entirely so you can self-check one instance in isolation. The `path` argument must end in `.json`. `instanceFiles` only contains real `.json` example paths (bare-instantiation fallbacks are filtered out) so any entry can be fed straight back into `path`. If a bare instantiation fails, its failure entry has `path: ''` and a populated `cardName` — identify the spec by `cardName` and do NOT pass the empty path back into `path`. When a failure reports a line/column, those numbers refer to the transpiled module — pair with `fetch_transpiled_module` to locate the offending source construct, then fix the `.gts` source (never copy transpiled patterns back into source).
+- `run_evaluate({ path? })` — Evaluate ESM modules (`.gts` / `.gjs` / `.ts` / `.js`) in the target realm via the prerenderer sandbox and return a `RunEvaluateResult` (status, module counts, per-failure `{ path, error, stackTrace? }`). Without `path`, evaluates every non-test evaluable module. With `path`, evaluates only that single realm-relative file — handy for a quick self-check right after writing one module. Test files (`*.test.*`) are rejected — the test runner validates those. When a failure reports a line/column, those numbers refer to the transpiled module — pair with `read_transpiled` to locate the offending source construct, then fix the `.gts` source (never copy transpiled patterns back into source).
+- `run_instantiate({ path? })` — Instantiate card example instances in the target realm via the prerenderer sandbox and return a `RunInstantiateResult` (status, instance counts, per-failure `{ path, cardName, error, stackTrace? }`). Without `path`, searches the realm for Spec cards and instantiates every `linkedExample` on every card/app Spec; specs with no `linkedExamples` still get a bare instantiation to exercise the card class. With `path`, instantiates only that single realm-relative `.json` example file — its `meta.adoptsFrom` supplies the module + card name, and spec discovery is skipped entirely so you can self-check one instance in isolation. The `path` argument must end in `.json`. `instanceFiles` only contains real `.json` example paths (bare-instantiation fallbacks are filtered out) so any entry can be fed straight back into `path`. If a bare instantiation fails, its failure entry has `path: ''` and a populated `cardName` — identify the spec by `cardName` and do NOT pass the empty path back into `path`. When a failure reports a line/column, those numbers refer to the transpiled module — pair with `read_transpiled` to locate the offending source construct, then fix the `.gts` source (never copy transpiled patterns back into source).
 
 ### Control Flow
 
@@ -77,14 +78,14 @@ All five tools are safe to call repeatedly mid-turn; none of them write a realm
 
 ## Required Flow
 
-1. **Inspect before writing.** Use `search_realm` and `read_file` to understand what already exists in the target realm before creating or modifying files.
-2. **Write card definitions** (`.gts`) via `write_file` to the target realm.
-3. **Write `.test.gts` test files** co-located with card definitions via `write_file` to the target realm. Every issue must have at least one test file. **Write tests immediately after the card definition, before any instances or catalog specs.**
-4. **Write card instances** (`.json`) via `write_file` to the target realm.
+1. **Inspect before writing.** Use `realm_search` (with the target realm URL as `realm-url`) plus your native `Read` / `Grep` / shell tools on the workspace dir to understand what already exists before creating or modifying files.
+2. **Write card definitions** (`.gts`) using your native `Write` tool into the workspace.
+3. **Write `.test.gts` test files** co-located with card definitions, using your native `Write` tool. Every issue must have at least one test file. **Write tests immediately after the card definition, before any instances or catalog specs.**
+4. **Write card instances** (`.json`) using your native `Write` tool. Place them in a folder named after the card type (e.g., `StickyNote/welcome-note.json`).
 5. **Write a Catalog Spec card** (`Spec/<card-name>.json`) for each top-level card defined in the brief. Link sample instances via `linkedExamples`.
 6. **(Optional) Call `run_tests()`** to self-validate before signalling done. This returns test results in-memory without writing any realm artifacts. Iterating on your own work with `run_tests` is faster than round-tripping through the orchestrator pipeline.
 7. **Call `signal_done()`** when all implementation and test files are written. The orchestrator runs the full validation pipeline (which persists a `TestRun` card, among other artifacts) automatically after this.
-8. **If tests fail**, the orchestrator feeds failure details back. Use `read_file` to inspect current state, then `write_file` to fix implementation or test files. Call `signal_done()` again.
+8. **If tests fail**, the orchestrator feeds failure details back. Use your native `Read` / `Edit` tools on the workspace to inspect and fix implementation or test files. Call `signal_done()` again.
 9. **Record progress** via `add_comment` — append notes, blocked reasons, or context to the issue. Never modify the issue description.
 
 ## Target Realm Artifact Structure
@@ -118,7 +119,7 @@ and runtime errors reference the compiled output.
 When a validation error contains text like
 `(error occurred in '/.../sticky-note.gts' @ line 66 : column 32)`, the
 line number is for the transpiled module. Call
-`fetch_transpiled_module({ path: 'sticky-note.gts' })` and read the
+`read_transpiled({ path: 'sticky-note.gts' })` and read the
 reported line to see what compiled construct raised the error — then
 reason back to the `.gts` source construct that produced it.
 
@@ -131,7 +132,7 @@ to the source.
 
 ### The transpiled output is for DEBUGGING ONLY — never for implementation
 
-**Scope of this tool:** `fetch_transpiled_module` is only for
+**Scope of this tool:** `read_transpiled` is only for
 investigating **runtime errors in `.gts` modules you have already
 written** — when an eval or instantiate validation failure points to
 a line/column in the transpiled output and you need to map that
@@ -156,7 +157,7 @@ reference.
   `boxel-development` skill and existing cards in the target realm are
   the right references — not what the compiler happens to emit.
 
-Use `fetch_transpiled_module` the way a developer uses a source map:
+Use `read_transpiled` the way a developer uses a source map:
 to translate a runtime line number back to a source construct in the
 code **you wrote**, then close the transpiled view and fix the source
 idiomatically.
@@ -204,8 +205,9 @@ export function runTests() {
 
 ## Important Rules
 
-- **Never write to the source realm.** All generated artifacts go to the target realm.
-- **Use realm HTTP APIs only.** The factory agent does not have access to the local filesystem or boxel CLI commands (`boxel sync`, `boxel push`, etc.). All reads and writes go through the realm API via tool functions.
+- **Never write to the source realm.** All generated artifacts go to the target realm (i.e., the workspace dir, which the loop syncs to the realm).
+- **Edit the workspace for target-realm files.** Target-realm files live in a local workspace directory — use your native `Read` / `Write` / `Edit` / shell tools on them. The loop handles target-realm sync between turns. For any other realm operation, use the available tools.
+- **Realm-server tools require `realm-url`.** `realm_search` / `realm_read_file` / `realm_write_file` / `realm_delete_file` / `realm_lint_file` all take an explicit `realm-url`. The realm-mutating ones (`realm_write_file` / `realm_delete_file`) are reserved for non-target realms; for the target realm, edit the workspace.
 - **Write source code, not compiled output.** When writing `.gts` files, write clean idiomatic source — never compiled JSON blocks or base64-encoded content.
 - **Use absolute `adoptsFrom.module` URLs** when referencing definitions that live in a different realm (e.g., the source realm's tracker schema).
 - **Start small and iterate.** Write the smallest working implementation first, then add the test. If tests fail, read the failure output carefully before making targeted fixes.
diff --git a/packages/software-factory/package.json b/packages/software-factory/package.json
index 577681b905c..384f0e18670 100644
--- a/packages/software-factory/package.json
+++ b/packages/software-factory/package.json
@@ -65,8 +65,5 @@
     "typescript": "catalog:",
     "zod": "^4.0.17",
     "zod-from-json-schema": "^0.5.2"
-  },
-  "volta": {
-    "extends": "../../package.json"
   }
 }
diff --git a/packages/software-factory/prompts/bootstrap-implement.md b/packages/software-factory/prompts/bootstrap-implement.md
index 9987cdbcd26..cd49979a884 100644
--- a/packages/software-factory/prompts/bootstrap-implement.md
+++ b/packages/software-factory/prompts/bootstrap-implement.md
@@ -17,9 +17,13 @@ Description:
 
 ## What to Create
 
-Create the following artifacts in the target realm using the available tools
-(`write_file`, `update_issue`, `create_knowledge`). Use `search_realm` and
-`read_file` to inspect existing state before creating anything.
+Create the following artifacts in the target realm. The target realm is
+mounted as a local workspace dir — write `.json` and `.gts` files with
+your native `Write` / `Edit` tools, and use the `update_issue` /
+`create_knowledge` tools (which operate on workspace files too) for
+schema-aware card updates. Use `realm_search` (pass the target realm URL
+as `realm-url`) and your native `Read` / `Grep` tools to inspect existing
+state before creating anything.
 
 ### 1. Project Card
 
@@ -110,7 +114,7 @@ dependency cards are implemented before cards that consume them.
 
 ## Instructions
 
-1. Use `read_file` to read the brief at the URL above (if it is in a realm) or use the brief content in the description
+1. Read the brief at the URL above — if the URL points to a non-target realm, use `realm_read_file` with that realm's URL; if it's already in the target workspace, use your native `Read` tool. If the brief content is inlined in the description, just use that.
 2. Derive the slug and project code from the brief title
 3. Create the Project card
 4. Create Knowledge Article cards (at least brief context + agent onboarding)
diff --git a/packages/software-factory/prompts/system.md b/packages/software-factory/prompts/system.md
index f0d3c8a96f3..c9042aae4f7 100644
--- a/packages/software-factory/prompts/system.md
+++ b/packages/software-factory/prompts/system.md
@@ -3,9 +3,12 @@
 You are a software factory agent. You implement Boxel cards and tests in
 target realms based on ticket descriptions and project context.
 
-You have access to tools for reading and writing files to realms, searching
-realm state, and signaling completion. Use these tools to inspect existing
-state before making changes — do not guess.
+The target realm is mounted as a local workspace directory — edit those
+files with your native `Read` / `Write` / `Edit` / shell tools. The
+orchestration loop pre-syncs the target realm into the workspace before
+your turn and pushes back after. For any other realm operation, use the
+available tools. Inspect existing state before making changes — do not
+guess.
 
 # Rules
 
@@ -13,14 +16,13 @@ state before making changes — do not guess.
 - For each top-level card defined in the brief, create a Catalog Spec card
   in the target realm's Spec/ folder (adoptsFrom https://cardstack.com/base/spec#Spec)
   and at least one sample card instance linked via linkedExamples.
-- Use search_realm and read_file to inspect existing cards before creating files.
+- Use realm_search to inspect realm-indexed state and your native filesystem tools to inspect workspace files before creating new files. realm_search takes an explicit `realm-url` argument — pass the target realm URL when searching the realm you're implementing against.
 - If you cannot proceed, call request_clarification with a description of what
   is blocked.
 - When all implementation and test files have been written, call signal_done.
 - Issue descriptions are immutable after creation. Never modify an issue's
   description. Use add_comment to append context, blocked reasons, or updates.
-- All file operations use the realm HTTP API. Write card definitions as .gts
-  files and card instances as .json files.
+- Target-realm files are edited in the local workspace using native filesystem tools. Write card definitions as .gts files and card instances as .json files.
 - After you call signal_done, the orchestrator automatically runs a validation
   pipeline that executes your .test.gts files and reports results. If tests
   fail, you will receive the failure details in your next iteration so you
diff --git a/packages/software-factory/prompts/ticket-implement.md b/packages/software-factory/prompts/ticket-implement.md
index 80c75568193..e9cafccd598 100644
--- a/packages/software-factory/prompts/ticket-implement.md
+++ b/packages/software-factory/prompts/ticket-implement.md
@@ -56,10 +56,10 @@ You previously invoked the following tools. Use these results to inform your imp
 
 Implement this issue in this order:
 
-1. Use search_realm and read_file to inspect existing realm state
-2. Use write_file to create or update card definitions (.gts) in the target realm
-3. Use write_file to create QUnit test files (.test.gts) co-located with card definitions — write tests BEFORE any sample instances or catalog specs. **Wrap every test in a QUnit `module(...)` block named after the card or feature under test** (e.g., `module('StickyNote', function (hooks) { ... test(...) ... })`). The TestRun card groups results by module name, so tests left at the top level all collapse into a single "default" bucket and become hard to read.
-4. Create at least one sample card instance (.json) in the target realm
+1. Use realm_search (pass the target realm URL as `realm-url`) and your native filesystem tools (Read / Grep / shell) on the workspace dir to inspect existing realm state
+2. Use your native Write tool to create or update card definitions (.gts) in the workspace
+3. Use your native Write tool to create QUnit test files (.test.gts) co-located with card definitions — write tests BEFORE any sample instances or catalog specs. **Wrap every test in a QUnit `module(...)` block named after the card or feature under test** (e.g., `module('StickyNote', function (hooks) { ... test(...) ... })`). The TestRun card groups results by module name, so tests left at the top level all collapse into a single "default" bucket and become hard to read.
+4. Create at least one sample card instance (.json) in the workspace
 5. Create a Catalog Spec card in the Spec/ folder for the top-level card (adoptsFrom https://cardstack.com/base/spec#Spec), linking sample instances via linkedExamples
 6. Call signal_done when all implementation and test files have been written
 
diff --git a/packages/software-factory/prompts/ticket-iterate.md b/packages/software-factory/prompts/ticket-iterate.md
index 4aa8b500966..81c2c4a1f34 100644
--- a/packages/software-factory/prompts/ticket-iterate.md
+++ b/packages/software-factory/prompts/ticket-iterate.md
@@ -53,9 +53,9 @@ All validation steps passed.
 
 Fix the validation failures shown above. You have the same tools available. You can:
 
-- Use read_file to inspect the current state of your implementation
-- Use write_file to update implementation or test files
-- Use search_realm to check what cards exist
+- Use your native Read / Grep / shell tools on the workspace dir to inspect the current state of your implementation
+- Use your native Write / Edit tools to update implementation or test files
+- Use realm_search (with the target realm URL as `realm-url`) to check what cards exist
 - If a lint violation is in your code, fix the code to pass lint
 - If the test expectation is wrong, fix the test
 - If the implementation is wrong, fix the implementation
diff --git a/packages/software-factory/prompts/ticket-test.md b/packages/software-factory/prompts/ticket-test.md
index 9c339e0e3ae..cc4a126524f 100644
--- a/packages/software-factory/prompts/ticket-test.md
+++ b/packages/software-factory/prompts/ticket-test.md
@@ -23,4 +23,4 @@ Tests must:
 - Verify card-specific behavior, field values, and relationships
 - Keep all test data in browser memory — no external realm writes
 
-Use write_file to create test files, then call signal_done.
+Use your native Write tool to create test files in the workspace, then call signal_done.
diff --git a/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts b/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts
index a9a0ece1074..c864351c7d7 100644
--- a/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts
+++ b/packages/software-factory/scripts/smoke-tests/factory-tools-smoke.ts
@@ -21,7 +21,13 @@ import {
   ToolExecutor,
   ToolNotFoundError,
   ToolSafetyError,
+  enforceRealmSafety,
 } from '../../src/factory-tool-executor';
+import {
+  adaptBoxelTool,
+  type FactoryTool,
+} from '../../src/factory-tool-builder';
+import { getToolDefinitions } from '@cardstack/boxel-cli/api';
 
 function makeMockClient(fetchImpl: typeof globalThis.fetch): BoxelCLIClient {
   async function jsonFetch(
@@ -188,9 +194,11 @@ async function main(): Promise<void> {
     log.info('');
   }
 
+  // The executor's registry only owns script tools now. Realm-side tools
+  // come from boxel-cli's getToolDefinitions and are wrapped via
+  // adaptBoxelTool — they're never dispatched through ToolExecutor.
+  check('only script tools registered', Object.keys(byCategory).length === 1);
   check('has script tools', byCategory['script']?.length === 2);
-  check('has boxel-cli tools', byCategory['boxel-cli']?.length === 6);
-  check('has realm-api tools', byCategory['realm-api']?.length === 5);
   check(
     'all names unique',
     new Set(manifests.map((m) => m.name)).size === manifests.length,
@@ -256,12 +264,22 @@ async function main(): Promise<void> {
     check('rejects source realm', err instanceof ToolSafetyError);
   }
 
-  // Unknown realm targeting (realm-api)
+  // Unknown realm targeting — exercise the standalone safety guard the
+  // factory wraps around boxel-cli tools (these tools are never dispatched
+  // through ToolExecutor, so we call enforceRealmSafety directly).
   try {
-    await executor.execute('realm-read', {
-      'realm-url': 'https://evil.example.test/hacker/realm/',
-      path: 'secrets.json',
-    });
+    enforceRealmSafety(
+      'realm_read_file',
+      {
+        'realm-url': 'https://evil.example.test/hacker/realm/',
+        path: 'secrets.json',
+      },
+      {
+        targetRealmUrl: 'https://realms.example.test/user/target/',
+        sourceRealmUrl: 'https://realms.example.test/user/source/',
+        allowedRealmPrefixes: ['https://realms.example.test/user/scratch-'],
+      },
+    );
     check('rejects unknown realm', false, 'did not throw');
   } catch (err) {
     check('rejects unknown realm', err instanceof ToolSafetyError);
@@ -290,38 +308,74 @@ async function main(): Promise<void> {
     );
   }) as typeof globalThis.fetch;
   let mockClient = makeMockClient(mockFetch);
-  let mockExecutor = new ToolExecutor(registry, {
-    packageRoot: process.cwd(),
-    targetRealmUrl: 'https://realms.example.test/user/target/',
-    client: mockClient,
+  // Build the realm-side tools the way the factory does at runtime:
+  // pull from boxel-cli's getToolDefinitions and wrap each with the
+  // standalone safety guard. ToolExecutor doesn't dispatch these tools —
+  // they live in boxel-cli and execute directly against the client.
+  let mockTargetRealm = 'https://realms.example.test/user/target/';
+  let scratchRealm = 'https://realms.example.test/user/scratch-1/';
+  let mockBoxelTools = getToolDefinitions(mockClient, {
+    targetRealmUrl: mockTargetRealm,
+    realmServerUrl: 'https://realms.example.test/',
   });
+  function findBoxelTool(name: string): FactoryTool {
+    let tool = mockBoxelTools.find((t) => t.name === name);
+    if (!tool) {
+      throw new Error(`boxel-cli tool "${name}" not in getToolDefinitions`);
+    }
+    return adaptBoxelTool(tool, {
+      targetRealmUrl: mockTargetRealm,
+      allowedRealmPrefixes: ['https://realms.example.test/user/scratch-'],
+    });
+  }
 
-  let readResult = await mockExecutor.execute('realm-read', {
-    'realm-url': 'https://realms.example.test/user/target/',
+  let realmRead = findBoxelTool('realm_read_file');
+  let readResult = await realmRead.execute({
+    'realm-url': scratchRealm,
     path: 'CardDef/hello.gts',
   });
-  check('realm-read exitCode=0', readResult.exitCode === 0);
-  check('realm-read has output', readResult.output !== undefined);
   check(
-    `realm-read duration ${readResult.durationMs}ms`,
-    readResult.durationMs >= 0,
+    'realm_read_file returns a result',
+    readResult !== undefined && readResult !== null,
   );
 
-  let searchResult = await mockExecutor.execute('realm-search', {
-    'realm-url': 'https://realms.example.test/user/target/',
+  let realmSearch = findBoxelTool('realm_search');
+  let searchResult = (await realmSearch.execute({
+    'realm-url': scratchRealm,
     query: JSON.stringify({ filter: { type: { name: 'Issue' } } }),
-  });
-  check('realm-search exitCode=0', searchResult.exitCode === 0);
+  })) as { data?: unknown[]; error?: string };
+  check('realm_search returns data', Array.isArray(searchResult.data));
 
-  let writeResult = await mockExecutor.execute('realm-write', {
-    'realm-url': 'https://realms.example.test/user/target/',
+  let realmWrite = findBoxelTool('realm_write_file');
+  let writeResult = (await realmWrite.execute({
+    'realm-url': scratchRealm,
     path: 'CardDef/new.gts',
     content: 'export class NewCard {}',
-  });
-  check('realm-write exitCode=0', writeResult.exitCode === 0);
+  })) as { ok: boolean };
+  check('realm_write_file ok', writeResult.ok === true);
 
   check(`mock fetch called ${mockCallCount} times`, mockCallCount === 3);
 
+  // Safety guard rejects realm_write_file targeting the target realm —
+  // those edits must go through the local workspace.
+  try {
+    await realmWrite.execute({
+      'realm-url': mockTargetRealm,
+      path: 'CardDef/new.gts',
+      content: 'should be rejected',
+    });
+    check(
+      'realm_write_file rejects target-realm target',
+      false,
+      'did not throw',
+    );
+  } catch (err) {
+    check(
+      'realm_write_file rejects target-realm target',
+      err instanceof ToolSafetyError,
+    );
+  }
+
   // -----------------------------------------------------------------------
   // 5. FactoryTool builder
   // -----------------------------------------------------------------------
@@ -367,18 +421,29 @@ async function main(): Promise<void> {
   );
 
   let toolNames = factoryTools.map((t) => t.name);
+  let factoryDomainNames = [
+    'run_lint',
+    'run_tests',
+    'run_evaluate',
+    'run_parse',
+    'run_instantiate',
+    'signal_done',
+    'request_clarification',
+    'update_project',
+    'update_issue',
+    'create_knowledge',
+    'create_catalog_spec',
+    'add_comment',
+  ];
   log.info(`  Built ${factoryTools.length} tools:`);
   log.info(
-    `    factory: ${toolNames.filter((n) => ['write_file', 'read_file', 'search_realm', 'run_command', 'signal_done', 'request_clarification', 'update_project', 'update_issue', 'create_knowledge'].includes(n)).join(', ')}`,
+    `    factory: ${toolNames.filter((n) => factoryDomainNames.includes(n)).join(', ')}`,
   );
   log.info(
-    `    registered: ${toolNames.filter((n) => !['write_file', 'read_file', 'search_realm', 'run_command', 'signal_done', 'request_clarification', 'update_project', 'update_issue', 'create_knowledge'].includes(n)).join(', ')}`,
+    `    boxel-cli + script: ${toolNames.filter((n) => !factoryDomainNames.includes(n)).join(', ')}`,
   );
   log.info('');
 
-  check('has write_file tool', toolNames.includes('write_file'));
-  check('has read_file tool', toolNames.includes('read_file'));
-  check('has search_realm tool', toolNames.includes('search_realm'));
   check('has signal_done tool', toolNames.includes('signal_done'));
   check(
     'has request_clarification tool',
@@ -386,37 +451,30 @@ async function main(): Promise<void> {
   );
   check('includes registered script tools', toolNames.includes('search-realm'));
   check(
-    'includes registered realm-api tools',
-    toolNames.includes('realm-read'),
+    'includes boxel-cli realm tools',
+    toolNames.includes('realm_read_file') &&
+      toolNames.includes('realm_search') &&
+      toolNames.includes('realm_lint_file'),
+  );
+  check(
+    'no workspace fs tools (agent uses native FS)',
+    !toolNames.includes('read_file') && !toolNames.includes('write_file'),
   );
 
-  // Test write_file with .gts (module source)
-  let writeFileTool = factoryTools.find((t) => t.name === 'write_file')!;
-  toolBuilderFetchCount = 0;
-  let gtsResult = (await writeFileTool.execute({
-    path: 'my-card.gts',
-    content: 'export class MyCard {}',
-  })) as { ok: boolean };
-  check('write_file .gts succeeds', gtsResult.ok === true);
-  check('write_file .gts made HTTP call', toolBuilderFetchCount === 1);
-
-  // Test write_file with .json (card source)
-  toolBuilderFetchCount = 0;
-  let jsonResult = (await writeFileTool.execute({
-    path: 'Card/1.json',
-    content: JSON.stringify({ data: { type: 'card', attributes: {} } }),
-  })) as { ok: boolean };
-  check('write_file .json succeeds', jsonResult.ok === true);
-  check('write_file .json made HTTP call', toolBuilderFetchCount === 1);
-
-  // Test write_file to test realm
+  // Exercise realm_search through the adopted boxel-cli tool — verify the
+  // adopter calls the boxel-cli execute function and threads the result
+  // back. The mock fetch returns `{ ok: true }` so the search shape isn't
+  // exercised here; the safety guard + dispatch path is what we're checking.
   toolBuilderFetchCount = 0;
-  await writeFileTool.execute({
-    path: 'Tests/spec.ts',
-    content: 'test content',
-    realm: 'test',
+  let realmSearchTool = factoryTools.find((t) => t.name === 'realm_search')!;
+  let searchOutput = await realmSearchTool.execute({
+    'realm-url': 'https://realms.example.test/user/target/',
+    query: JSON.stringify({ filter: { type: { name: 'CardDef' } } }),
   });
-  check('write_file to test realm made HTTP call', toolBuilderFetchCount === 1);
+  check(
+    'realm_search via builder hit the realm and returned a result',
+    toolBuilderFetchCount === 1 && searchOutput !== undefined,
+  );
 
   // Test signal_done
   let doneTool = factoryTools.find((t) => t.name === 'signal_done')!;
diff --git a/packages/software-factory/src/factory-agent/claude-code.ts b/packages/software-factory/src/factory-agent/claude-code.ts
index 64a74aa2834..024ed804d90 100644
--- a/packages/software-factory/src/factory-agent/claude-code.ts
+++ b/packages/software-factory/src/factory-agent/claude-code.ts
@@ -202,11 +202,11 @@ export class ClaudeCodeFactoryAgent implements LoopAgent {
     });
 
     // The shared prompt template references tools by their plain names
-    // (`read_file`, `signal_done`, etc.) — which is what OpenRouter's
+    // (`realm_search`, `signal_done`, etc.) — which is what OpenRouter's
     // tool-use protocol registers. The Claude Agent SDK exposes tools via
     // an MCP server and prefixes every tool name with `mcp__<server>__`,
-    // so without a bridge the model can see "write_file" in the prompt
-    // but only `mcp__factory__write_file` in its tool list. Append a
+    // so without a bridge the model can see "realm_search" in the prompt
+    // but only `mcp__factory__realm_search` in its tool list. Append a
     // short tool-naming note so the model can resolve the two
     // consistently. The OpenRouter path leaves the template untouched.
     let renameList = tools
diff --git a/packages/software-factory/src/factory-agent/types.ts b/packages/software-factory/src/factory-agent/types.ts
index 4a288a6613d..30eded2f997 100644
--- a/packages/software-factory/src/factory-agent/types.ts
+++ b/packages/software-factory/src/factory-agent/types.ts
@@ -123,7 +123,7 @@ export interface ToolArg {
 export interface ToolManifest {
   name: string;
   description: string;
-  category: 'script' | 'boxel-cli' | 'realm-api';
+  category: 'script';
   args: ToolArg[];
   outputFormat: 'json' | 'text';
 }
diff --git a/packages/software-factory/src/factory-issue-loop-wiring.ts b/packages/software-factory/src/factory-issue-loop-wiring.ts
index cad50059d38..43895618ebd 100644
--- a/packages/software-factory/src/factory-issue-loop-wiring.ts
+++ b/packages/software-factory/src/factory-issue-loop-wiring.ts
@@ -36,12 +36,8 @@ import {
   type FactoryTool,
   type ToolBuilderConfig,
 } from './factory-tool-builder';
-import { ToolExecutor } from './factory-tool-executor';
-import {
-  ToolRegistry,
-  SCRIPT_TOOLS,
-  REALM_API_TOOLS,
-} from './factory-tool-registry';
+import { ToolExecutor, buildRealmSafetyConfig } from './factory-tool-executor';
+import { ToolRegistry, SCRIPT_TOOLS } from './factory-tool-registry';
 import {
   runIssueLoop,
   createDefaultPipeline,
@@ -131,11 +127,15 @@ export async function runFactoryIssueLoop(
     issueLoader,
   });
 
-  // 3. Tool infrastructure
-  let toolRegistry = new ToolRegistry([...SCRIPT_TOOLS, ...REALM_API_TOOLS]);
+  // 3. Tool infrastructure — the registry only owns subprocess-dispatched
+  // tools (script + boxel-cli command wrappers). Realm-api tools come from
+  // boxel-cli's getToolDefinitions and are spread into the agent's
+  // FactoryTool[] in factory-tool-builder, wrapped with enforceRealmSafety.
+  let toolRegistry = new ToolRegistry([...SCRIPT_TOOLS]);
   let toolExecutor = new ToolExecutor(toolRegistry, {
     packageRoot: PACKAGE_ROOT,
-    targetRealmUrl,
+    ...buildRealmSafetyConfig({ targetRealmUrl, realmServerUrl }),
+    realmServerUrl,
     client,
     debug: config.debug,
   });
diff --git a/packages/software-factory/src/factory-tool-builder.ts b/packages/software-factory/src/factory-tool-builder.ts
index 553279c3292..47314cbe006 100644
--- a/packages/software-factory/src/factory-tool-builder.ts
+++ b/packages/software-factory/src/factory-tool-builder.ts
@@ -7,7 +7,11 @@
  * (realm protection, per-realm JWT auth, logging).
  */
 
-import type { BoxelCLIClient } from '@cardstack/boxel-cli/api';
+import type {
+  BoxelCLIClient,
+  BoxelToolDefinition,
+} from '@cardstack/boxel-cli/api';
+import { getToolDefinitions } from '@cardstack/boxel-cli/api';
 import type {
   LooseSingleCardDocument,
   Relationship,
@@ -20,7 +24,12 @@ import {
   type RunEvaluateInMemoryOptions,
   type RunEvaluateResult,
 } from './eval-execution';
-import type { ToolExecutor } from './factory-tool-executor';
+import {
+  buildRealmSafetyConfig,
+  enforceRealmSafety,
+  type RealmSafetyConfig,
+  type ToolExecutor,
+} from './factory-tool-executor';
 import type { ToolRegistry } from './factory-tool-registry';
 import {
   runInstantiateInMemory,
@@ -142,12 +151,13 @@ export function buildFactoryTools(
   toolExecutor: ToolExecutor,
   toolRegistry: ToolRegistry,
 ): FactoryTool[] {
+  // Factory-domain orchestration tools (validation runners + signal tools).
+  // Files in the workspace are managed by the agent's native filesystem
+  // tools (Read/Write/Edit/shell) rather than dedicated tool calls — those
+  // primitives are strictly more efficient and capable than wrapping fs in
+  // a Node-backed tool. Realm-server-side I/O lives in boxel-cli's
+  // getToolDefinitions and is merged in below.
   let tools: FactoryTool[] = [
-    buildWriteFileTool(config),
-    buildReadFileTool(config),
-    buildFetchTranspiledModuleTool(config),
-    buildSearchRealmTool(config),
-    buildRunCommandTool(config),
     buildRunLintTool(config),
     buildRunTestsTool(config),
     buildRunEvaluateTool(config),
@@ -157,6 +167,23 @@ export function buildFactoryTools(
     buildRequestClarificationTool(),
   ];
 
+  // Adopt every boxel-cli tool from getToolDefinitions and wrap each one
+  // with `enforceRealmSafety` so the agent can't bypass the target-realm
+  // guard or hit the source realm by mis-passing a `realm-url`. boxel-cli
+  // is the single source of truth for the wire shape — descriptions,
+  // schemas, and execute live there.
+  let safety = buildRealmSafetyConfig({
+    targetRealmUrl: config.targetRealmUrl,
+    realmServerUrl: config.realmServerUrl,
+  });
+  let boxelTools = getToolDefinitions(config.client, {
+    targetRealmUrl: config.targetRealmUrl,
+    realmServerUrl: config.realmServerUrl,
+  });
+  for (let boxelTool of boxelTools) {
+    tools.push(adaptBoxelTool(boxelTool, safety));
+  }
+
   // add_comment doesn't need runtime schemas — it reads/patches directly.
   tools.push(buildAddCommentTool(config));
 
@@ -182,10 +209,12 @@ export function buildFactoryTools(
     }
   }
 
-  // Add registered script/realm-api tools as FactoryTool wrappers.
-  // Realm-api tools get the config so they can resolve per-realm JWTs.
+  // Add registered script tools as FactoryTool wrappers. The executor
+  // applies enforceRealmSafety inside its dispatch path; realm-api tools
+  // are NOT registered here — they're already adopted from boxel-cli's
+  // getToolDefinitions above.
   for (let manifest of toolRegistry.getManifests()) {
-    if (manifest.category === 'script' || manifest.category === 'realm-api') {
+    if (manifest.category === 'script') {
       tools.push(buildRegisteredTool(manifest, toolExecutor, config));
     }
   }
@@ -201,10 +230,10 @@ export function buildFactoryTools(
  * Enforce that a required string argument is present and non-empty. Returns
  * the trimmed value or throws a clear error that propagates back to the
  * model as a tool-call result. This is the only runtime guardrail against
- * an LLM emitting a malformed tool call like `write_file({})` — the JSON
- * Schema `required` declaration is advisory for OpenRouter's tool-use and
- * the model can still send empty args. Without this check, path strings
- * like `"undefined"` would end up at the realm's root (e.g., a file named
+ * an LLM emitting a malformed tool call with empty args — the JSON Schema
+ * `required` declaration is advisory for OpenRouter's tool-use and the
+ * model can still send empty args. Without this check, path strings like
+ * `"undefined"` would end up at the realm's root (e.g., a file named
  * `<realm>/undefined`).
  */
 export function requireStringArg(
@@ -226,119 +255,25 @@ export function requireStringArg(
 // Factory-level tools
 // ---------------------------------------------------------------------------
 
-function buildWriteFileTool(config: ToolBuilderConfig): FactoryTool {
-  return {
-    name: 'write_file',
-    description:
-      'Write a file to the target realm workspace. The path must include the file extension. Writes go to the local workspace and are synced to the realm between iterations.',
-    parameters: {
-      type: 'object',
-      properties: {
-        path: {
-          type: 'string',
-          description:
-            'Realm-relative file path with extension (e.g., "my-card.gts", "Card/1.json")',
-        },
-        content: { type: 'string', description: 'File content' },
-        realm: {
-          type: 'string',
-          enum: ['target'],
-          description: 'Which realm to write to (default: target)',
-        },
-      },
-      required: ['path', 'content'],
-    },
-    execute: async (args) => {
-      let path = requireStringArg(args, 'path', 'write_file');
-      let content = requireStringArg(args, 'content', 'write_file');
-      return writeCard(config.workspaceDir, path, content);
-    },
-  };
-}
-
-function buildReadFileTool(config: ToolBuilderConfig): FactoryTool {
-  return {
-    name: 'read_file',
-    description:
-      'Read a file from the target realm workspace. Returns parsed JSON when possible, otherwise raw text.',
-    parameters: {
-      type: 'object',
-      properties: {
-        path: {
-          type: 'string',
-          description: 'Realm-relative file path',
-        },
-        realm: {
-          type: 'string',
-          enum: ['target'],
-          description: 'Which realm to read from (default: target)',
-        },
-      },
-      required: ['path'],
-    },
-    execute: async (args) => {
-      let path = requireStringArg(args, 'path', 'read_file');
-      return readCard(config.workspaceDir, path);
-    },
-  };
-}
-
-function buildFetchTranspiledModuleTool(
-  config: ToolBuilderConfig,
+/**
+ * Wrap a `BoxelToolDefinition` from boxel-cli's `getToolDefinitions(...)`
+ * as a `FactoryTool` the agent can call. boxel-cli owns the wire shape
+ * (name, description, parameters, execute); the factory adds a
+ * `enforceRealmSafety` guard at the seam so the agent can't bypass the
+ * target-realm protection or hit the source realm by mis-passing a
+ * `realm-url`.
+ */
+export function adaptBoxelTool(
+  tool: BoxelToolDefinition,
+  safety: RealmSafetyConfig,
 ): FactoryTool {
   return {
-    name: 'fetch_transpiled_module',
-    description:
-      "Debugging tool ONLY for investigating runtime errors in .gts modules you've written. Use when an eval or instantiate validation error reports a line/column number — those line numbers refer to the transpiled output, not your .gts source, so fetching the transpiled output is how you locate the offending source construct. Never use the transpiled output as a reference for how to write code. Do NOT copy its patterns (setComponentTemplate, precompileTemplate, wire-format templates, base64 CSS imports) into source — always write idiomatic Ember / <template>-tag / CardDef source. Editing: only edit the .gts source (the transpiled output is regenerated on the next write). Auth: per-realm JWT.",
-    parameters: {
-      type: 'object',
-      properties: {
-        path: {
-          type: 'string',
-          description:
-            'Realm-relative module path. The .gts extension is optional — the realm accepts either form.',
-        },
-        realm: {
-          type: 'string',
-          enum: ['target'],
-          description: 'Which realm to read from (default: target)',
-        },
-      },
-      required: ['path'],
-    },
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
     execute: async (args) => {
-      let path = requireStringArg(args, 'path', 'fetch_transpiled_module');
-      let realmUrl = resolveRealmUrl(config, args.realm as string | undefined);
-      return config.client.readTranspiled(realmUrl, path);
-    },
-  };
-}
-
-function buildSearchRealmTool(config: ToolBuilderConfig): FactoryTool {
-  return {
-    name: 'search_realm',
-    description:
-      'Search for cards in a realm using a structured query. Auth: per-realm JWT.',
-    parameters: {
-      type: 'object',
-      properties: {
-        query: {
-          type: 'object',
-          description: 'Search query object (filter, sort, page)',
-        },
-        realm: {
-          type: 'string',
-          enum: ['target'],
-          description: 'Which realm to search (default: target)',
-        },
-      },
-      required: ['query'],
-    },
-    execute: async (args) => {
-      let query = args.query as Record<string, unknown>;
-      let realmUrl = resolveRealmUrl(config, args.realm as string | undefined);
-      let result = await config.client.search(realmUrl, query);
-      return result.ok ? { data: result.data } : { error: result.error };
+      enforceRealmSafety(tool.name, args, safety);
+      return tool.execute(args);
     },
   };
 }
@@ -695,7 +630,7 @@ function buildRunEvaluateTool(config: ToolBuilderConfig): FactoryTool {
       'orchestrator still runs the full validation pipeline (which writes ' +
       'an EvalResult card) automatically after signal_done, so calling ' +
       'this is optional. When a failure reports a line/column, those ' +
-      'numbers refer to the transpiled module — use `fetch_transpiled_module` ' +
+      'numbers refer to the transpiled module — use `read_transpiled` ' +
       'to locate the offending source construct, then fix the .gts source ' +
       '(never copy transpiled patterns back into source). Auth: realm ' +
       'server token.',
@@ -795,7 +730,7 @@ function buildRunInstantiateTool(config: ToolBuilderConfig): FactoryTool {
       'still runs the full validation pipeline (which writes an ' +
       'InstantiateResult card) automatically after signal_done, so calling ' +
       'this is optional. When a failure reports a line/column, those numbers ' +
-      'refer to the transpiled module — use `fetch_transpiled_module` to ' +
+      'refer to the transpiled module — use `read_transpiled` to ' +
       'locate the offending source construct, then fix the .gts source ' +
       '(never copy transpiled patterns back into source). Auth: realm server ' +
       'token.',
@@ -862,41 +797,6 @@ function buildRequestClarificationTool(): FactoryTool {
   };
 }
 
-function buildRunCommandTool(config: ToolBuilderConfig): FactoryTool {
-  return {
-    name: 'run_command',
-    description:
-      'Execute a Boxel host command on the realm server via the prerenderer. ' +
-      'This runs Boxel host commands ONLY — not shell commands, scripts, or Node.js. ' +
-      'Commands must be Boxel host command specifiers in the format ' +
-      '"@cardstack/boxel-host/commands/<name>/default". ' +
-      'Auth: realm server token.',
-    parameters: {
-      type: 'object',
-      properties: {
-        command: {
-          type: 'string',
-          description:
-            'Boxel host command specifier — must be in the format "@cardstack/boxel-host/commands/<name>/default"',
-        },
-        commandInput: {
-          type: 'object',
-          description: 'Optional input for the command',
-        },
-      },
-      required: ['command'],
-    },
-    execute: async (args) => {
-      return config.client.runCommand(
-        config.realmServerUrl,
-        config.targetRealmUrl,
-        args.command as string,
-        args.commandInput as Record<string, unknown> | undefined,
-      );
-    },
-  };
-}
-
 // ---------------------------------------------------------------------------
 // Registered tool wrappers (script + realm-api)
 // ---------------------------------------------------------------------------
@@ -942,14 +842,3 @@ function buildRegisteredTool(
     },
   };
 }
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function resolveRealmUrl(
-  config: ToolBuilderConfig,
-  _realm: string | undefined,
-): string {
-  return config.targetRealmUrl;
-}
diff --git a/packages/software-factory/src/factory-tool-executor.ts b/packages/software-factory/src/factory-tool-executor.ts
index 272f93d63e0..f55e432f9f7 100644
--- a/packages/software-factory/src/factory-tool-executor.ts
+++ b/packages/software-factory/src/factory-tool-executor.ts
@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
 
 import type { ToolResult } from './factory-agent';
 import type { ToolRegistry } from './factory-tool-registry';
+import { sourceRealmURLFor } from './harness/shared';
 import type { BoxelCLIClient } from '@cardstack/boxel-cli/api';
 import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
 
@@ -13,15 +14,16 @@ import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
 const DEFAULT_TIMEOUT_MS = 60_000;
 
 /**
- * Tools that perform HTTP-direct card I/O. The executor rejects these
- * when they target the factory's target realm — target-realm I/O must
- * go through the workspace (via `write_file` / `read_file`) so local
- * state stays in sync with the realm between iterations.
+ * Tools that perform HTTP-direct card I/O against a remote realm. The safety
+ * guard rejects these when they target the factory's target realm —
+ * target-realm I/O must go through the local workspace (using the agent's
+ * native filesystem tools) so local state stays in sync with the realm
+ * between iterations.
  */
 const TARGET_REALM_BYPASS_TOOLS = new Set([
-  'realm-read',
-  'realm-write',
-  'realm-delete',
+  'realm_read_file',
+  'realm_write_file',
+  'realm_delete_file',
 ]);
 
 /**
@@ -33,31 +35,56 @@ const SCRIPT_FILE_MAP: Record<string, string> = {
   'run-realm-tests': 'run-realm-tests.ts',
 };
 
-/**
- * Map from boxel-cli tool name to the `npx boxel` subcommand.
- */
-const BOXEL_CLI_COMMAND_MAP: Record<string, string> = {
-  'boxel-sync': 'sync',
-  'boxel-push': 'push',
-  'boxel-pull': 'pull',
-  'boxel-status': 'status',
-  'boxel-create': 'create',
-  'boxel-history': 'history',
-};
-
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-export interface ToolExecutorConfig {
-  /** Absolute path to the software-factory package root. */
-  packageRoot: string;
-  /** Target realm URL — tools may only target this realm. */
+/**
+ * Realm-targeting safety configuration. Used both by the executor (for
+ * subprocess-dispatched script tools) and by the boxel-cli tool adopter in
+ * factory-tool-builder (for tools spread directly into the agent's
+ * FactoryTool[]).
+ */
+export interface RealmSafetyConfig {
+  /** Target realm URL — `realm-url` args may target this realm only when the
+   * tool is NOT in TARGET_REALM_BYPASS_TOOLS. */
   targetRealmUrl: string;
+  /** Optional source realm URL — tools must NEVER target this realm. */
+  sourceRealmUrl?: string;
   /** Additional scratch realm URL prefixes that are allowed. */
   allowedRealmPrefixes?: string[];
-  /** Source realm URL — tools must NEVER target this realm. */
-  sourceRealmUrl?: string;
+}
+
+/**
+ * Derive the production safety config from the realm server URL. Source realm
+ * is always `<realmServerUrl>/software-factory/` (the factory's own realm —
+ * agent must never target it); allowed prefixes default to the realm server
+ * itself, letting `realm_*` tools target any realm hosted there modulo the
+ * source-realm rejection that fires first.
+ *
+ * Tests, smoke, and scenario harnesses construct `RealmSafetyConfig` directly
+ * with their own values; this helper is for the live factory loop.
+ */
+export function buildRealmSafetyConfig(opts: {
+  targetRealmUrl: string;
+  realmServerUrl: string;
+}): RealmSafetyConfig {
+  return {
+    targetRealmUrl: opts.targetRealmUrl,
+    sourceRealmUrl: sourceRealmURLFor(new URL(opts.realmServerUrl)).href,
+    allowedRealmPrefixes: [opts.realmServerUrl],
+  };
+}
+
+export interface ToolExecutorConfig extends RealmSafetyConfig {
+  /** Absolute path to the software-factory package root. */
+  packageRoot: string;
+  /**
+   * Realm server URL (host of the target realm). Reserved for callers
+   * that want to thread it through alongside the executor; the executor
+   * itself never reads it.
+   */
+  realmServerUrl?: string;
   /** Boxel CLI client — owns all realm auth and API calls. */
   client: BoxelCLIClient;
   /** Per-invocation timeout in ms (default: 60 000). */
@@ -74,7 +101,7 @@ export interface ToolExecutorConfig {
 
 export interface ToolExecutionLogEntry {
   tool: string;
-  category: 'script' | 'boxel-cli' | 'realm-api';
+  category: 'script';
   args: Record<string, unknown>;
   exitCode: number;
   durationMs: number;
@@ -107,7 +134,188 @@ export class ToolNotFoundError extends Error {
 }
 
 // ---------------------------------------------------------------------------
-// ToolExecutor
+// Standalone safety guard — exported so callers outside the executor
+// (notably factory-tool-builder's adoption of boxel-cli tools) can apply
+// the same checks before dispatching to a BoxelToolDefinition.execute.
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply realm-targeting safety checks to a tool invocation. Throws
+ * `ToolSafetyError` if any check fails:
+ *
+ *   - Source realm rejection: `realm` / `realm-url` / `realm-server-url`
+ *     / `local-dir` / `path` args matching the configured source realm.
+ *   - TARGET_REALM_BYPASS_TOOLS check: realm_read_file / realm_write_file /
+ *     realm_delete_file with `realm-url` matching the target realm.
+ *   - Allowed-target validation: realm-url args must match the target
+ *     realm exactly or one of the allowed scratch prefixes.
+ *   - realm-server-url: must point to a server origin hosting an allowed
+ *     realm.
+ *   - Destructive ops: extra realm-target check for realm_delete_file.
+ */
+export function enforceRealmSafety(
+  toolName: string,
+  toolArgs: Record<string, unknown>,
+  config: RealmSafetyConfig,
+): void {
+  // Source realm protection (when configured)
+  let sourceUrl = config.sourceRealmUrl;
+  if (sourceUrl) {
+    let normalizedSource = ensureTrailingSlash(sourceUrl);
+    let realmArgNames = [
+      'realm',
+      'realm-url',
+      'realm-server-url',
+      'local-dir',
+      'path',
+    ];
+    for (let argName of realmArgNames) {
+      let value = toolArgs[argName];
+      if (typeof value === 'string' && looksLikeUrl(value)) {
+        let normalizedValue = ensureTrailingSlash(value);
+        if (normalizedValue === normalizedSource) {
+          throw new ToolSafetyError(
+            `Tool "${toolName}" cannot target the source realm: ${sourceUrl}`,
+          );
+        }
+      }
+    }
+  }
+
+  // Allowed-target validation for all URL args across all tool categories.
+  // Prevents SSRF and token exfiltration via the propagated Authorization header.
+  let urlArgNames = ['realm', 'realm-url'];
+  for (let argName of urlArgNames) {
+    let value = toolArgs[argName];
+    if (typeof value === 'string' && looksLikeUrl(value)) {
+      validateRealmTarget(toolName, value, config);
+    }
+  }
+
+  // realm-server-url must match one of the allowed realm origins.
+  let serverUrl = toolArgs['realm-server-url'];
+  if (typeof serverUrl === 'string' && looksLikeUrl(serverUrl)) {
+    validateRealmServerTarget(toolName, serverUrl, config);
+  }
+
+  // Extra validation for destructive operations.
+  validateDestructiveOps(toolName, toolArgs, config);
+}
+
+function validateRealmTarget(
+  toolName: string,
+  realmUrl: string,
+  config: RealmSafetyConfig,
+): void {
+  let normalized = ensureTrailingSlash(realmUrl);
+  let target = ensureTrailingSlash(config.targetRealmUrl);
+
+  // The HTTP-direct card I/O tools (realm_read_file / realm_write_file / realm_delete_file)
+  // must NOT target the factory's target realm — those edits would bypass
+  // the local workspace and diverge from the sync flow. Use the agent's
+  // native filesystem tools on the workspace directory for target-realm I/O.
+  if (TARGET_REALM_BYPASS_TOOLS.has(toolName) && normalized === target) {
+    throw new ToolSafetyError(
+      `Tool "${toolName}" cannot target the target realm (${realmUrl}). ` +
+        `Use the agent's native filesystem tools on the workspace directory ` +
+        `instead — those edits sync to the realm between iterations. This ` +
+        `tool is reserved for scratch / non-target realms.`,
+    );
+  }
+
+  // Exact realm matches (with trailing slash normalization). For the
+  // target-bypass tools the target is excluded from the exact-allowed set —
+  // the rejection above fires first for target hits.
+  let exactAllowed = TARGET_REALM_BYPASS_TOOLS.has(toolName) ? [] : [target];
+
+  // Prefix matches: within-origin path-string prefixes. Origin equality is
+  // enforced separately (see isUrlWithinPrefix) so a configured prefix like
+  // `https://realms.example.test/user/scratch-` cannot be exploited by a
+  // sibling-host URL like `https://realms.example.test.evil.com/...`.
+  let prefixAllowed = config.allowedRealmPrefixes ?? [];
+
+  let isAllowed =
+    exactAllowed.some((exact) => normalized === exact) ||
+    prefixAllowed.some((prefix) => isUrlWithinPrefix(normalized, prefix));
+
+  if (!isAllowed) {
+    throw new ToolSafetyError(
+      `Tool "${toolName}" targets realm "${realmUrl}" which is not in the allowed list. ` +
+        `Allowed: ${[...exactAllowed, ...prefixAllowed].join(', ')}`,
+    );
+  }
+}
+
+function isUrlWithinPrefix(url: string, prefix: string): boolean {
+  let urlObj: URL;
+  let prefixObj: URL;
+  try {
+    urlObj = new URL(url);
+    prefixObj = new URL(prefix);
+  } catch {
+    return false;
+  }
+  if (urlObj.origin !== prefixObj.origin) return false;
+  let urlPath = urlObj.pathname + urlObj.search;
+  let prefixPath = prefixObj.pathname + prefixObj.search;
+  return urlPath.startsWith(prefixPath);
+}
+
+function validateRealmServerTarget(
+  toolName: string,
+  serverUrl: string,
+  config: RealmSafetyConfig,
+): void {
+  let normalizedServer: string;
+  try {
+    normalizedServer = new URL(serverUrl).origin;
+  } catch {
+    throw new ToolSafetyError(
+      `Tool "${toolName}" has invalid realm-server-url: "${serverUrl}"`,
+    );
+  }
+
+  let allowedOrigins = new Set<string>();
+  try {
+    allowedOrigins.add(new URL(config.targetRealmUrl).origin);
+  } catch {
+    // skip invalid
+  }
+  for (let prefix of config.allowedRealmPrefixes ?? []) {
+    try {
+      allowedOrigins.add(new URL(prefix).origin);
+    } catch {
+      // skip invalid
+    }
+  }
+
+  if (!allowedOrigins.has(normalizedServer)) {
+    throw new ToolSafetyError(
+      `Tool "${toolName}" targets server "${serverUrl}" which is not in the allowed origins. ` +
+        `Allowed: ${[...allowedOrigins].join(', ')}`,
+    );
+  }
+}
+
+function validateDestructiveOps(
+  toolName: string,
+  toolArgs: Record<string, unknown>,
+  config: RealmSafetyConfig,
+): void {
+  // Extra validation for destructive realm operations
+  if (toolName === 'realm_delete_file') {
+    let realmUrl = toolArgs['realm-url'];
+    if (typeof realmUrl === 'string') {
+      validateRealmTarget(toolName, realmUrl, config);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ToolExecutor — dispatches subprocess-backed script tools. Realm-api
+// tools (read/write/delete/search/sync/push/pull/etc.) live in boxel-cli's
+// getToolDefinitions and are wrapped with `enforceRealmSafety` directly in
+// factory-tool-builder without going through the executor.
 // ---------------------------------------------------------------------------
 
 export class ToolExecutor {
@@ -122,13 +330,11 @@ export class ToolExecutor {
   }
 
   /**
-   * Execute a tool by name with the given arguments and return the result.
-   *
-   * The executor:
+   * Execute a registered subprocess-backed script tool by name. The executor:
    * 1. Validates the tool name against the registry
    * 2. Validates arguments against the manifest
-   * 3. Enforces safety constraints (no source realm targeting)
-   * 4. Dispatches to the appropriate sub-executor
+   * 3. Enforces realm-targeting safety constraints
+   * 4. Spawns the script subprocess (npx ts-node ...)
    * 5. Captures output as a ToolResult
    */
   async execute(
@@ -144,7 +350,7 @@ export class ToolExecutor {
       throw new ToolNotFoundError(toolName);
     }
 
-    // Validate required args
+    // Validate required args.
     let argErrors = this.registry.validateArgs(toolName, toolArgs);
     if (argErrors.length > 0) {
       throw new Error(
@@ -152,40 +358,31 @@ export class ToolExecutor {
       );
     }
 
-    // Safety: reject source realm targeting
-    this.enforceRealmSafety(toolName, toolArgs);
+    // Realm-targeting safety.
+    enforceRealmSafety(toolName, toolArgs, this.config);
 
     let start = Date.now();
     let result: ToolResult;
 
     try {
-      switch (manifest.category) {
-        case 'script':
-          result = await this.executeScript(toolName, toolArgs);
-          break;
-        case 'boxel-cli':
-          result = await this.executeBoxelCli(toolName, toolArgs);
-          break;
-        case 'realm-api':
-          result = await this.executeRealmApi(toolName, toolArgs);
-          break;
-        default:
-          throw new Error(`Unknown tool category: ${manifest.category}`);
+      if (manifest.category !== 'script') {
+        throw new Error(`Unknown tool category: ${manifest.category}`);
       }
+      result = await this.executeScript(toolName, toolArgs);
     } catch (error) {
       let durationMs = Date.now() - start;
       let errorMessage = error instanceof Error ? error.message : String(error);
 
       this.logExecution({
         tool: toolName,
-        category: manifest.category,
+        category: 'script',
         args: toolArgs,
         exitCode: 1,
         durationMs,
         error: errorMessage,
       });
 
-      // Re-throw safety and timeout errors as-is
+      // Re-throw safety and timeout errors as-is.
       if (
         error instanceof ToolSafetyError ||
         error instanceof ToolTimeoutError ||
@@ -204,7 +401,7 @@ export class ToolExecutor {
 
     this.logExecution({
       tool: toolName,
-      category: manifest.category,
+      category: 'script',
       args: toolArgs,
       exitCode: result.exitCode,
       durationMs: result.durationMs,
@@ -213,158 +410,6 @@ export class ToolExecutor {
     return result;
   }
 
-  // -------------------------------------------------------------------------
-  // Safety
-  // -------------------------------------------------------------------------
-
-  private enforceRealmSafety(
-    toolName: string,
-    toolArgs: Record<string, unknown>,
-  ): void {
-    // Source realm protection (when configured)
-    let sourceUrl = this.config.sourceRealmUrl;
-    if (sourceUrl) {
-      let normalizedSource = ensureTrailingSlash(sourceUrl);
-
-      let realmArgNames = [
-        'realm',
-        'realm-url',
-        'realm-server-url',
-        'local-dir',
-        'path',
-      ];
-
-      for (let argName of realmArgNames) {
-        let value = toolArgs[argName];
-        if (typeof value === 'string' && looksLikeUrl(value)) {
-          let normalizedValue = ensureTrailingSlash(value);
-          if (normalizedValue === normalizedSource) {
-            throw new ToolSafetyError(
-              `Tool "${toolName}" cannot target the source realm: ${sourceUrl}`,
-            );
-          }
-        }
-      }
-    }
-
-    // Allowed-target validation for all URL args across all tool categories.
-    // Prevents SSRF and token exfiltration via the propagated Authorization header.
-    let urlArgNames = ['realm', 'realm-url'];
-    for (let argName of urlArgNames) {
-      let value = toolArgs[argName];
-      if (typeof value === 'string' && looksLikeUrl(value)) {
-        this.validateRealmTarget(toolName, value);
-      }
-    }
-
-    // realm-server-url must match one of the allowed realm origins
-    let serverUrl = toolArgs['realm-server-url'];
-    if (typeof serverUrl === 'string' && looksLikeUrl(serverUrl)) {
-      this.validateRealmServerTarget(toolName, serverUrl);
-    }
-
-    // Extra validation for destructive operations
-    this.validateDestructiveOps(toolName, toolArgs);
-  }
-
-  private validateRealmTarget(toolName: string, realmUrl: string): void {
-    let normalized = ensureTrailingSlash(realmUrl);
-    let target = ensureTrailingSlash(this.config.targetRealmUrl);
-
-    // The HTTP-direct card I/O tools (realm-read / realm-write / realm-delete)
-    // must NOT target the factory's target realm — those edits would bypass
-    // the local workspace and diverge from the sync flow. The agent uses
-    // write_file / read_file (workspace-backed) for target-realm I/O and
-    // keeps these HTTP-direct tools for scratch / non-target realms.
-    if (TARGET_REALM_BYPASS_TOOLS.has(toolName) && normalized === target) {
-      throw new ToolSafetyError(
-        `Tool "${toolName}" cannot target the target realm (${realmUrl}). ` +
-          `Use write_file / read_file instead — they operate on the local ` +
-          `workspace and sync to the realm between iterations. This tool is ` +
-          `reserved for scratch / non-target realms.`,
-      );
-    }
-
-    // Exact realm matches (with trailing slash normalization). For the
-    // target-bypass tools the target is explicitly excluded from the
-    // exact-allowed set — the rejection above fires first for target hits.
-    let exactAllowed = TARGET_REALM_BYPASS_TOOLS.has(toolName) ? [] : [target];
-
-    // Prefix matches (no trailing slash — these are URL path prefixes)
-    let prefixAllowed = this.config.allowedRealmPrefixes ?? [];
-
-    let isAllowed =
-      exactAllowed.some((exact) => normalized === exact) ||
-      prefixAllowed.some((prefix) => normalized.startsWith(prefix));
-
-    if (!isAllowed) {
-      throw new ToolSafetyError(
-        `Tool "${toolName}" targets realm "${realmUrl}" which is not in the allowed list. ` +
-          `Allowed: ${[...exactAllowed, ...prefixAllowed].join(', ')}`,
-      );
-    }
-  }
-
-  /**
-   * Validate that a realm-server-url arg points to a server that hosts
-   * one of the allowed realms (origin match against target/test/prefixes).
-   */
-  private validateRealmServerTarget(toolName: string, serverUrl: string): void {
-    let normalizedServer: string;
-    try {
-      normalizedServer = new URL(serverUrl).origin;
-    } catch {
-      throw new ToolSafetyError(
-        `Tool "${toolName}" has invalid realm-server-url: "${serverUrl}"`,
-      );
-    }
-
-    let allowedOrigins = new Set<string>();
-    try {
-      allowedOrigins.add(new URL(this.config.targetRealmUrl).origin);
-    } catch {
-      // skip invalid
-    }
-    for (let prefix of this.config.allowedRealmPrefixes ?? []) {
-      try {
-        allowedOrigins.add(new URL(prefix).origin);
-      } catch {
-        // skip invalid
-      }
-    }
-
-    if (!allowedOrigins.has(normalizedServer)) {
-      throw new ToolSafetyError(
-        `Tool "${toolName}" targets server "${serverUrl}" which is not in the allowed origins. ` +
-          `Allowed: ${[...allowedOrigins].join(', ')}`,
-      );
-    }
-  }
-
-  private validateDestructiveOps(
-    toolName: string,
-    toolArgs: Record<string, unknown>,
-  ): void {
-    // Extra validation for destructive realm operations
-    if (toolName === 'realm-delete') {
-      let realmUrl = toolArgs['realm-url'];
-      if (typeof realmUrl === 'string') {
-        this.validateRealmTarget(toolName, realmUrl);
-      }
-    }
-
-    // boxel-push with --delete
-    if (toolName === 'boxel-push' && toolArgs['delete']) {
-      let realmUrl = toolArgs['realm-url'];
-      if (typeof realmUrl === 'string' && looksLikeUrl(realmUrl)) {
-        this.validateRealmTarget(toolName, realmUrl);
-      }
-    }
-
-    // realm-create is allowed but logged — the orchestrator trusts the agent
-    // chose it deliberately within the allowed realm set.
-  }
-
   // -------------------------------------------------------------------------
   // Sub-executors
   // -------------------------------------------------------------------------
@@ -390,172 +435,6 @@ export class ToolExecutor {
     );
   }
 
-  private async executeBoxelCli(
-    toolName: string,
-    toolArgs: Record<string, unknown>,
-  ): Promise<ToolResult> {
-    let subcommand = BOXEL_CLI_COMMAND_MAP[toolName];
-    if (!subcommand) {
-      throw new Error(`No boxel-cli command mapped for tool "${toolName}"`);
-    }
-
-    let cliArgs = buildBoxelCliArgs(toolName, subcommand, toolArgs);
-    let invocation = composeBoxelCliInvocation(cliArgs, {
-      debug: this.config.debug,
-    });
-
-    return this.spawnProcess(toolName, 'npx', invocation, 'text');
-  }
-
-  private async executeRealmApi(
-    toolName: string,
-    toolArgs: Record<string, unknown>,
-  ): Promise<ToolResult> {
-    return this.withTimeout(
-      toolName,
-      this.executeRealmApiInner(toolName, toolArgs),
-    );
-  }
-
-  /**
-   * Race an operation against `this.timeoutMs` and throw `ToolTimeoutError`
-   * if the timeout wins. `BoxelCLIClient` methods don't accept an
-   * AbortSignal (auth + retry live inside ProfileManager), so we enforce
-   * the timeout at the executor boundary — the in-flight request becomes
-   * best-effort and is reaped by the GC.
-   */
-  private async withTimeout<T>(toolName: string, op: Promise<T>): Promise<T> {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    let timeoutPromise = new Promise<never>((_, reject) => {
-      timer = setTimeout(() => {
-        reject(new ToolTimeoutError(toolName, this.timeoutMs));
-      }, this.timeoutMs);
-    });
-    try {
-      return await Promise.race([op, timeoutPromise]);
-    } finally {
-      if (timer) {
-        clearTimeout(timer);
-      }
-    }
-  }
-
-  private async executeRealmApiInner(
-    toolName: string,
-    toolArgs: Record<string, unknown>,
-  ): Promise<ToolResult> {
-    let client = this.config.client;
-    let start = Date.now();
-
-    let output: unknown;
-    let ok: boolean;
-
-    switch (toolName) {
-      case 'realm-read': {
-        let result = await client.read(
-          String(toolArgs['realm-url']),
-          String(toolArgs['path']),
-        );
-        ok = result.ok;
-        output = ok ? JSON.parse(result.content!) : { error: result.error };
-        break;
-      }
-
-      case 'realm-write': {
-        let result = await client.write(
-          String(toolArgs['realm-url']),
-          String(toolArgs['path']),
-          String(toolArgs['content']),
-        );
-        ok = result.ok;
-        output = ok ? result : { error: result.error };
-        break;
-      }
-
-      case 'realm-delete': {
-        let result = await client.delete(
-          String(toolArgs['realm-url']),
-          String(toolArgs['path']),
-        );
-        ok = result.ok;
-        output = ok ? result : { error: result.error };
-        break;
-      }
-
-      case 'realm-search': {
-        let rawQuery = toolArgs['query'];
-        if (typeof rawQuery !== 'string') {
-          ok = false;
-          output = {
-            error:
-              "Invalid 'query' argument for realm-search: expected a JSON string.",
-          };
-          break;
-        }
-        let query: Record<string, unknown>;
-        try {
-          query = JSON.parse(rawQuery);
-        } catch {
-          ok = false;
-          output = {
-            error:
-              "Invalid JSON for 'query' in realm-search: expected valid JSON.",
-          };
-          break;
-        }
-        let result = await client.search(String(toolArgs['realm-url']), query);
-        ok = result.ok;
-        output = result.ok
-          ? { data: result.data }
-          : { error: result.error, status: result.status };
-        break;
-      }
-
-      case 'realm-create': {
-        let displayName = String(toolArgs['name']);
-        let realmName = String(toolArgs['endpoint']);
-        let requestedServerUrl = ensureTrailingSlash(
-          String(toolArgs['realm-server-url']),
-        );
-        try {
-          let active = client.getActiveProfile();
-          if (
-            active &&
-            ensureTrailingSlash(active.realmServerUrl) !== requestedServerUrl
-          ) {
-            throw new Error(
-              `realm-create cannot target "${requestedServerUrl}": active Boxel profile realm server is "${ensureTrailingSlash(active.realmServerUrl)}".`,
-            );
-          }
-          let result = await client.createRealm({
-            realmName,
-            displayName,
-            iconURL: toolArgs['iconURL'] as string | undefined,
-            backgroundURL: toolArgs['backgroundURL'] as string | undefined,
-          });
-          ok = true;
-          output = { data: { id: result.realmUrl } };
-        } catch (error) {
-          ok = false;
-          output = {
-            error: error instanceof Error ? error.message : String(error),
-          };
-        }
-        break;
-      }
-
-      default:
-        throw new Error(`Unknown realm-api tool: "${toolName}"`);
-    }
-
-    return {
-      tool: toolName,
-      exitCode: ok ? 0 : 1,
-      output,
-      durationMs: Date.now() - start,
-    };
-  }
-
   // -------------------------------------------------------------------------
   // Process spawning
   // -------------------------------------------------------------------------
@@ -646,27 +525,6 @@ export class ToolExecutor {
 // Helpers: CLI arg building
 // ---------------------------------------------------------------------------
 
-/**
- * Compose the full `npx boxel ...` argument vector for an `executeBoxelCli`
- * call. Prepends `--quiet` to silence boxel-cli's chatty per-step progress
- * logs ("Starting sync …", "Downloaded: …", "Checkpoint created: …") so they
- * don't surface in the factory's tool output or CI logs. Errors, warnings,
- * and the command's actual result payload still come through — see
- * `packages/boxel-cli/src/lib/cli-log.ts`.
- *
- * When `debug` is true (factory itself is running with `--debug`), `--quiet`
- * is omitted so the full boxel-cli logs surface for debugging.
- */
-export function composeBoxelCliInvocation(
-  cliArgs: string[],
-  options: { debug?: boolean } = {},
-): string[] {
-  if (options.debug) {
-    return ['boxel', ...cliArgs];
-  }
-  return ['boxel', '--quiet', ...cliArgs];
-}
-
 function buildCliArgs(toolArgs: Record<string, unknown>): string[] {
   let args: string[] = [];
 
@@ -691,108 +549,6 @@ function buildCliArgs(toolArgs: Record<string, unknown>): string[] {
   return args;
 }
 
-function buildBoxelCliArgs(
-  _toolName: string,
-  subcommand: string,
-  toolArgs: Record<string, unknown>,
-): string[] {
-  let args: string[] = [subcommand];
-
-  // Certain tools use positional args rather than flags
-  switch (subcommand) {
-    case 'sync': {
-      let path = toolArgs['path'];
-      if (typeof path === 'string') {
-        args.push(path);
-      }
-      if (typeof toolArgs['prefer'] === 'string') {
-        args.push(`--prefer-${toolArgs['prefer']}`);
-      }
-      if (toolArgs['dry-run']) {
-        args.push('--dry-run');
-      }
-      break;
-    }
-    case 'push': {
-      let localDir = toolArgs['local-dir'];
-      let realmUrl = toolArgs['realm-url'];
-      if (typeof localDir === 'string') {
-        args.push(localDir);
-      }
-      if (typeof realmUrl === 'string') {
-        args.push(realmUrl);
-      }
-      if (toolArgs['delete']) {
-        args.push('--delete');
-      }
-      if (toolArgs['dry-run']) {
-        args.push('--dry-run');
-      }
-      break;
-    }
-    case 'pull': {
-      let realmUrl = toolArgs['realm-url'];
-      let localDir = toolArgs['local-dir'];
-      if (typeof realmUrl === 'string') {
-        args.push(realmUrl);
-      }
-      if (typeof localDir === 'string') {
-        args.push(localDir);
-      }
-      if (toolArgs['delete']) {
-        args.push('--delete');
-      }
-      if (toolArgs['dry-run']) {
-        args.push('--dry-run');
-      }
-      break;
-    }
-    case 'status': {
-      let path = toolArgs['path'];
-      if (typeof path === 'string') {
-        args.push(path);
-      }
-      if (toolArgs['all']) {
-        args.push('--all');
-      }
-      if (toolArgs['pull']) {
-        args.push('--pull');
-      }
-      break;
-    }
-    case 'create': {
-      let endpoint = toolArgs['endpoint'];
-      let name = toolArgs['name'];
-      if (typeof endpoint === 'string') {
-        args.push(endpoint);
-      }
-      if (typeof name === 'string') {
-        args.push(name);
-      }
-      break;
-    }
-    case 'history': {
-      let path = toolArgs['path'];
-      if (typeof path === 'string') {
-        args.push(path);
-      }
-      if (typeof toolArgs['message'] === 'string') {
-        args.push('-m', toolArgs['message']);
-      }
-      break;
-    }
-    default:
-      // Fall through to generic flag building
-      args.push(...buildCliArgs(toolArgs));
-  }
-
-  return args;
-}
-
-// ---------------------------------------------------------------------------
-// Utilities
-// ---------------------------------------------------------------------------
-
 function looksLikeUrl(value: string): boolean {
-  return value.startsWith('http://') || value.startsWith('https://');
+  return /^https?:\/\//i.test(value);
 }
diff --git a/packages/software-factory/src/factory-tool-registry.ts b/packages/software-factory/src/factory-tool-registry.ts
index 162ab491d9f..fd46d1bd55f 100644
--- a/packages/software-factory/src/factory-tool-registry.ts
+++ b/packages/software-factory/src/factory-tool-registry.ts
@@ -109,299 +109,14 @@ const SCRIPT_TOOLS: ToolManifest[] = [
   },
 ];
 
-const BOXEL_CLI_TOOLS: ToolManifest[] = [
-  {
-    name: 'boxel-sync',
-    description: 'Bidirectional sync between local workspace and realm server.',
-    category: 'boxel-cli',
-    outputFormat: 'text',
-    args: [
-      {
-        name: 'path',
-        type: 'string',
-        required: true,
-        description: 'Local workspace path',
-      },
-      {
-        name: 'prefer',
-        type: 'string',
-        required: false,
-        description: 'Conflict strategy: "local", "remote", or "newest"',
-      },
-      {
-        name: 'dry-run',
-        type: 'boolean',
-        required: false,
-        description: 'Preview only, no changes',
-      },
-    ],
-  },
-  {
-    name: 'boxel-push',
-    description: 'One-way upload from local directory to realm.',
-    category: 'boxel-cli',
-    outputFormat: 'text',
-    args: [
-      {
-        name: 'local-dir',
-        type: 'string',
-        required: true,
-        description: 'Local directory path',
-      },
-      {
-        name: 'realm-url',
-        type: 'string',
-        required: true,
-        description: 'Target realm URL',
-      },
-      {
-        name: 'delete',
-        type: 'boolean',
-        required: false,
-        description: 'Remove orphaned remote files',
-      },
-      {
-        name: 'dry-run',
-        type: 'boolean',
-        required: false,
-        description: 'Preview only, no changes',
-      },
-    ],
-  },
-  {
-    name: 'boxel-pull',
-    description: 'One-way download from realm to local directory.',
-    category: 'boxel-cli',
-    outputFormat: 'text',
-    args: [
-      {
-        name: 'realm-url',
-        type: 'string',
-        required: true,
-        description: 'Source realm URL',
-      },
-      {
-        name: 'local-dir',
-        type: 'string',
-        required: true,
-        description: 'Local directory path',
-      },
-      {
-        name: 'delete',
-        type: 'boolean',
-        required: false,
-        description: 'Delete local files not on remote',
-      },
-      {
-        name: 'dry-run',
-        type: 'boolean',
-        required: false,
-        description: 'Preview only, no changes',
-      },
-    ],
-  },
-  {
-    name: 'boxel-status',
-    description: 'Check sync status of a workspace.',
-    category: 'boxel-cli',
-    outputFormat: 'text',
-    args: [
-      {
-        name: 'path',
-        type: 'string',
-        required: true,
-        description: 'Local workspace path',
-      },
-      {
-        name: 'all',
-        type: 'boolean',
-        required: false,
-        description: 'Check all workspaces',
-      },
-      {
-        name: 'pull',
-        type: 'boolean',
-        required: false,
-        description: 'Auto-pull remote changes',
-      },
-    ],
-  },
-  {
-    name: 'boxel-create',
-    description: 'Create a new workspace/realm endpoint.',
-    category: 'boxel-cli',
-    outputFormat: 'text',
-    args: [
-      {
-        name: 'endpoint',
-        type: 'string',
-        required: true,
-        description: 'Endpoint type',
-      },
-      {
-        name: 'name',
-        type: 'string',
-        required: true,
-        description: 'Workspace name',
-      },
-    ],
-  },
-  {
-    name: 'boxel-history',
-    description: 'View or create checkpoints for a workspace.',
-    category: 'boxel-cli',
-    outputFormat: 'text',
-    args: [
-      {
-        name: 'path',
-        type: 'string',
-        required: true,
-        description: 'Local workspace path',
-      },
-      {
-        name: 'message',
-        type: 'string',
-        required: false,
-        description: 'Checkpoint message',
-      },
-    ],
-  },
-];
-
-const REALM_API_TOOLS: ToolManifest[] = [
-  {
-    name: 'realm-read',
-    description:
-      'Fetch a card or file from a realm over HTTP. For the factory target realm, use `read_file` instead — it reads from the local workspace and stays in sync with the realm. This tool is reserved for scratch / non-target realms. Auth: per-realm JWT.',
-    category: 'realm-api',
-    outputFormat: 'json',
-    args: [
-      {
-        name: 'realm-url',
-        type: 'string',
-        required: true,
-        description: 'Realm base URL (must not be the target realm)',
-      },
-      {
-        name: 'path',
-        type: 'string',
-        required: true,
-        description: 'Card or file path within the realm',
-      },
-    ],
-  },
-  {
-    name: 'realm-write',
-    description:
-      'Create or update a card or file in a realm over HTTP. For the factory target realm, use `write_file` instead — it writes to the local workspace and syncs to the realm between iterations. This tool is reserved for scratch / non-target realms. Auth: per-realm JWT.',
-    category: 'realm-api',
-    outputFormat: 'json',
-    args: [
-      {
-        name: 'realm-url',
-        type: 'string',
-        required: true,
-        description: 'Realm base URL (must not be the target realm)',
-      },
-      {
-        name: 'path',
-        type: 'string',
-        required: true,
-        description: 'Card or file path within the realm',
-      },
-      {
-        name: 'content',
-        type: 'string',
-        required: true,
-        description: 'File content to write',
-      },
-    ],
-  },
-  {
-    name: 'realm-delete',
-    description:
-      'Delete a card or file from a realm over HTTP. For the factory target realm, delete through the workspace (remove the file locally, it will be propagated on the next sync). This tool is reserved for scratch / non-target realms. Auth: per-realm JWT.',
-    category: 'realm-api',
-    outputFormat: 'json',
-    args: [
-      {
-        name: 'realm-url',
-        type: 'string',
-        required: true,
-        description: 'Realm base URL (must not be the target realm)',
-      },
-      {
-        name: 'path',
-        type: 'string',
-        required: true,
-        description: 'Card or file path to delete',
-      },
-    ],
-  },
-  {
-    name: 'realm-search',
-    description:
-      'Search for cards using structured queries. Auth: per-realm JWT.',
-    category: 'realm-api',
-    outputFormat: 'json',
-    args: [
-      {
-        name: 'realm-url',
-        type: 'string',
-        required: true,
-        description: 'Realm base URL',
-      },
-      {
-        name: 'query',
-        type: 'string',
-        required: true,
-        description: 'JSON search query object',
-      },
-    ],
-  },
-  {
-    name: 'realm-create',
-    description:
-      'Create a new realm on the realm server. Auth: realm server token.',
-    category: 'realm-api',
-    outputFormat: 'json',
-    args: [
-      {
-        name: 'realm-server-url',
-        type: 'string',
-        required: true,
-        description: 'Realm server base URL',
-      },
-      {
-        name: 'name',
-        type: 'string',
-        required: true,
-        description: 'Display name for the new realm',
-      },
-      {
-        name: 'endpoint',
-        type: 'string',
-        required: true,
-        description:
-          'URL path segment for the new realm (e.g. "user/my-realm")',
-      },
-      {
-        name: 'iconURL',
-        type: 'string',
-        required: false,
-        description:
-          'Icon URL for the realm. Defaults to a letter-based icon derived from the realm name.',
-      },
-      {
-        name: 'backgroundURL',
-        type: 'string',
-        required: false,
-        description:
-          'Background image URL for the realm. Defaults to a random background image.',
-      },
-    ],
-  },
-];
+// ---------------------------------------------------------------------------
+// Realm-api tools (read/write/delete/search/sync/push/pull/etc.) are NOT
+// registered here. They live in boxel-cli's `getToolDefinitions(...)` and
+// are spread directly into the agent's FactoryTool[] in factory-tool-builder,
+// wrapped with `enforceRealmSafety` at adoption time. The registry only owns
+// subprocess-dispatched script tools — those go through ToolExecutor.execute
+// for spawn / stdout capture / timeout.
+// ---------------------------------------------------------------------------
 
 // ---------------------------------------------------------------------------
 // ToolRegistry
@@ -411,11 +126,11 @@ export class ToolRegistry {
   private manifestsByName: Map<string, ToolManifest>;
 
   constructor(manifests?: ToolManifest[]) {
-    let allManifests = manifests ?? [
-      ...SCRIPT_TOOLS,
-      ...BOXEL_CLI_TOOLS,
-      ...REALM_API_TOOLS,
-    ];
+    // The default registry includes only the factory-defined script
+    // manifests. Realm-api tools come from boxel-cli's getToolDefinitions
+    // and are spread directly into the agent's tool list via
+    // factory-tool-builder, not registered here.
+    let allManifests = manifests ?? [...SCRIPT_TOOLS];
     let map = new Map<string, ToolManifest>();
     for (let manifest of allManifests) {
       if (map.has(manifest.name)) {
@@ -495,10 +210,4 @@ export function getDefaultToolRegistry(): ToolRegistry {
 }
 
 // Re-export the built-in manifest arrays for testing
-export {
-  SCRIPT_TOOLS,
-  BOXEL_CLI_TOOLS,
-  REALM_API_TOOLS,
-  type ToolArg,
-  type ToolManifest,
-};
+export { SCRIPT_TOOLS, type ToolArg, type ToolManifest };
diff --git a/packages/software-factory/src/harness/database.ts b/packages/software-factory/src/harness/database.ts
index 735b342222f..e6537c69083 100644
--- a/packages/software-factory/src/harness/database.ts
+++ b/packages/software-factory/src/harness/database.ts
@@ -426,7 +426,7 @@ export async function rewriteClonedRealmServerUrls(
         // Without this, lookupDefinition misses every cached module on the
         // first request after clone and pays a full prerender (~45s for a
         // module with deep transitive imports), which can blow past the
-        // 60s realm-search tool timeout.
+        // 60s realm_search tool timeout.
         await client.query(
           `UPDATE modules
            SET url = replace(url, $1, $2),
diff --git a/packages/software-factory/tests/factory-prompt-loader.test.ts b/packages/software-factory/tests/factory-prompt-loader.test.ts
index 3ba805a5a23..59f6f386aa9 100644
--- a/packages/software-factory/tests/factory-prompt-loader.test.ts
+++ b/packages/software-factory/tests/factory-prompt-loader.test.ts
@@ -197,7 +197,10 @@ module('factory-prompt-loader > FilePromptLoader', function () {
       result.includes('signal_done'),
       'system prompt contains signal_done',
     );
-    assert.ok(result.includes('read_file'), 'system prompt contains read_file');
+    assert.ok(
+      result.includes('realm_search'),
+      'system prompt contains realm_search',
+    );
   });
 
   test('caches templates on subsequent loads', function (assert) {
@@ -251,7 +254,10 @@ module('factory-prompt-loader > assembleSystemPrompt', function () {
       result.includes('signal_done'),
       'includes signal_done instruction',
     );
-    assert.ok(result.includes('read_file'), 'includes read_file instruction');
+    assert.ok(
+      result.includes('realm_search'),
+      'includes realm_search instruction',
+    );
   });
 
   test('includes realm URLs', function (assert) {
diff --git a/packages/software-factory/tests/factory-tool-builder.test.ts b/packages/software-factory/tests/factory-tool-builder.test.ts
index 39f1d71977b..49eb27bd328 100644
--- a/packages/software-factory/tests/factory-tool-builder.test.ts
+++ b/packages/software-factory/tests/factory-tool-builder.test.ts
@@ -241,16 +241,12 @@ function findTool(tools: FactoryTool[], name: string): FactoryTool {
 
 module('factory-tool-builder > tool building', function () {
   test('builds factory-level tools plus registered tools', function (assert) {
-    let registry = new ToolRegistry();
     let { executor } = createMockToolExecutor(new Map());
     let config = makeConfig();
-    let tools = buildFactoryTools(config, executor, registry);
+    let tools = buildFactoryTools(config, executor, new ToolRegistry());
 
     let toolNames = tools.map((t) => t.name);
 
-    assert.true(toolNames.includes('write_file'));
-    assert.true(toolNames.includes('read_file'));
-    assert.true(toolNames.includes('search_realm'));
     assert.true(toolNames.includes('update_issue'));
     assert.true(toolNames.includes('add_comment'));
     assert.true(toolNames.includes('create_knowledge'));
@@ -258,8 +254,13 @@ module('factory-tool-builder > tool building', function () {
     assert.true(toolNames.includes('request_clarification'));
     // Script tools from registry
     assert.true(toolNames.includes('search-realm'));
-    // Realm-api tools from registry
-    assert.true(toolNames.includes('realm-read'));
+    // Realm-api tools come directly from boxel-cli's getToolDefinitions and
+    // are spread into the agent's tool list, wrapped with enforceRealmSafety.
+    assert.true(toolNames.includes('realm_read_file'));
+    assert.true(toolNames.includes('realm_search'));
+    assert.true(toolNames.includes('create_realm'));
+    assert.true(toolNames.includes('run_command'));
+    assert.true(toolNames.includes('read_transpiled'));
   });
 
   test('each tool has name, description, parameters, and execute', function (assert) {
@@ -279,84 +280,14 @@ module('factory-tool-builder > tool building', function () {
   });
 });
 
-// ---------------------------------------------------------------------------
-// write_file: file routing (.gts vs .json)
-// ---------------------------------------------------------------------------
-
-module('factory-tool-builder > write_file', function () {
-  test('writes .gts file to the workspace with raw text body', async function (assert) {
-    let registry = new ToolRegistry();
-    let { executor } = createMockToolExecutor(new Map());
-    let config = makeConfig();
-    let ws = workspaceFor(config);
-    let tools = buildFactoryTools(config, executor, registry);
-    let writeTool = findTool(tools, 'write_file');
-
-    let result = (await writeTool.execute({
-      path: 'my-card.gts',
-      content: 'export default class MyCard {}',
-    })) as { ok: boolean };
-
-    assert.true(result.ok);
-    assert.true(ws.exists('my-card.gts'), 'workspace has my-card.gts');
-    assert.strictEqual(
-      ws.read('my-card.gts'),
-      'export default class MyCard {}',
-    );
-  });
-
-  test('writes nested .ts path to the workspace', async function (assert) {
-    let registry = new ToolRegistry();
-    let { executor } = createMockToolExecutor(new Map());
-    let config = makeConfig();
-    let ws = workspaceFor(config);
-    let tools = buildFactoryTools(config, executor, registry);
-    let writeTool = findTool(tools, 'write_file');
-
-    let result = (await writeTool.execute({
-      path: 'utils/helpers.ts',
-      content: 'export function helper() {}',
-    })) as { ok: boolean };
-
-    assert.true(result.ok);
-    assert.strictEqual(
-      ws.read('utils/helpers.ts'),
-      'export function helper() {}',
-    );
-  });
-
-  test('writes .json file as raw content (no JSON parsing)', async function (assert) {
-    let registry = new ToolRegistry();
-    let { executor } = createMockToolExecutor(new Map());
-    let config = makeConfig();
-    let ws = workspaceFor(config);
-    let tools = buildFactoryTools(config, executor, registry);
-    let writeTool = findTool(tools, 'write_file');
-
-    let cardJson = JSON.stringify({
-      data: { type: 'card', attributes: { title: 'Test Card' } },
-    });
-
-    let result = (await writeTool.execute({
-      path: 'Card/1.json',
-      content: cardJson,
-    })) as { ok: boolean };
-
-    assert.true(result.ok);
-    // Content is written verbatim — no re-serialization by write_file.
-    assert.strictEqual(ws.read('Card/1.json'), cardJson);
-  });
-});
-
 // ---------------------------------------------------------------------------
 // Argument validation (guards against malformed LLM tool calls)
 // ---------------------------------------------------------------------------
 
 /**
  * The OpenRouter tool-use protocol treats `required` on parameter schemas
- * as advisory: models can still emit `tool_call` with an empty args blob
- * (`write_file({})`). Without runtime validation, the factory would
- * silently write to `<realm>/undefined` because `path` stringifies to the
+ * as advisory: models can still emit `tool_call` with an empty args blob.
+ * Without runtime validation, the factory would silently downstream the
  * literal "undefined" further down the call chain.
  *
  * These tests assert that every path-taking tool rejects
@@ -387,79 +318,17 @@ module('factory-tool-builder > path-arg validation', function () {
     );
   }
 
-  test('write_file({}) throws and does NOT hit the realm', async function (assert) {
-    let { fetch: mockFetch, requests } = createMockFetch(200, {});
-    let registry = new ToolRegistry();
-    let { executor } = createMockToolExecutor(new Map());
-    let config = makeConfig({ fetch: mockFetch });
-    let tools = buildFactoryTools(config, executor, registry);
-    let writeTool = findTool(tools, 'write_file');
-
-    await expectPathError(() => writeTool.execute({}), 'write_file', assert);
-    assert.strictEqual(
-      requests.length,
-      0,
-      'no realm HTTP request was made for an empty write_file call',
-    );
-  });
-
-  test('write_file with empty-string path throws', async function (assert) {
-    let { fetch: mockFetch } = createMockFetch(200, {});
-    let registry = new ToolRegistry();
-    let { executor } = createMockToolExecutor(new Map());
-    let config = makeConfig({ fetch: mockFetch });
-    let tools = buildFactoryTools(config, executor, registry);
-    let writeTool = findTool(tools, 'write_file');
-
-    await expectPathError(
-      () => writeTool.execute({ path: '   ', content: 'x' }),
-      'write_file',
-      assert,
-    );
-  });
-
-  test('write_file with missing content throws (required arg)', async function (assert) {
-    let { fetch: mockFetch, requests } = createMockFetch(200, {});
-    let registry = new ToolRegistry();
-    let { executor } = createMockToolExecutor(new Map());
-    let config = makeConfig({ fetch: mockFetch });
-    let tools = buildFactoryTools(config, executor, registry);
-    let writeTool = findTool(tools, 'write_file');
-
-    let err: Error | undefined;
-    try {
-      await writeTool.execute({ path: 'card.gts' });
-    } catch (e) {
-      err = e as Error;
-    }
-    assert.ok(err);
-    assert.true(/non-empty string "content"/.test(err?.message ?? ''));
-    assert.strictEqual(requests.length, 0, 'no write request was made');
-  });
-
-  test('read_file({}) throws and does NOT hit the realm', async function (assert) {
-    let { fetch: mockFetch, requests } = createMockFetch(200, {});
-    let registry = new ToolRegistry();
-    let { executor } = createMockToolExecutor(new Map());
-    let config = makeConfig({ fetch: mockFetch });
-    let tools = buildFactoryTools(config, executor, registry);
-    let readTool = findTool(tools, 'read_file');
-
-    await expectPathError(() => readTool.execute({}), 'read_file', assert);
-    assert.strictEqual(requests.length, 0);
-  });
-
-  test('fetch_transpiled_module({}) throws', async function (assert) {
+  test('read_transpiled({}) throws', async function (assert) {
     let { fetch: mockFetch } = createMockFetch(200, {});
     let registry = new ToolRegistry();
     let { executor } = createMockToolExecutor(new Map());
     let config = makeConfig({ fetch: mockFetch });
     let tools = buildFactoryTools(config, executor, registry);
-    let fetchTool = findTool(tools, 'fetch_transpiled_module');
+    let fetchTool = findTool(tools, 'read_transpiled');
 
     await expectPathError(
       () => fetchTool.execute({}),
-      'fetch_transpiled_module',
+      'read_transpiled',
       assert,
     );
   });
@@ -548,39 +417,6 @@ module('factory-tool-builder > path-arg validation', function () {
 // ---------------------------------------------------------------------------
 
 module('factory-tool-builder > realm targeting', function () {
-  test('write_file writes to the workspace (target realm)', async function (assert) {
-    let registry = new ToolRegistry();
-    let { executor } = createMockToolExecutor(new Map());
-    let config = makeConfig();
-    let ws = workspaceFor(config);
-    let tools = buildFactoryTools(config, executor, registry);
-    let writeTool = findTool(tools, 'write_file');
-
-    await writeTool.execute({ path: 'card.gts', content: 'content' });
-
-    assert.true(ws.exists('card.gts'));
-    assert.strictEqual(ws.read('card.gts'), 'content');
-  });
-
-  test('read_file reads from the workspace (target realm)', async function (assert) {
-    let registry = new ToolRegistry();
-    let { executor } = createMockToolExecutor(new Map());
-    let config = makeConfig();
-    let ws = workspaceFor(config);
-    // Pre-seed the workspace with the file the agent will read.
-    ws.write('card.gts', 'export class Card {}');
-    let tools = buildFactoryTools(config, executor, registry);
-    let readTool = findTool(tools, 'read_file');
-
-    let result = (await readTool.execute({ path: 'card.gts' })) as {
-      ok: boolean;
-      content?: string;
-    };
-
-    assert.true(result.ok);
-    assert.strictEqual(result.content, 'export class Card {}');
-  });
-
   test('update_issue reads from and writes to the workspace', async function (assert) {
     let registry = new ToolRegistry();
     let { executor } = createMockToolExecutor(new Map());
@@ -635,19 +471,26 @@ module('factory-tool-builder > realm targeting', function () {
     assert.strictEqual(written.data.attributes.articleTitle, 'Guide');
   });
 
-  test('search_realm targets target realm', async function (assert) {
+  test('realm_search calls client.search with the supplied realm-url', async function (assert) {
     let { fetch: mockFetch, requests } = createMockFetch(200, { data: [] });
-    let registry = new ToolRegistry();
     let { executor } = createMockToolExecutor(new Map());
     let config = makeConfig({ fetch: mockFetch });
-    let tools = buildFactoryTools(config, executor, registry);
-    let searchTool = findTool(tools, 'search_realm');
+    let tools = buildFactoryTools(config, executor, new ToolRegistry());
+    let searchTool = findTool(tools, 'realm_search');
 
     await searchTool.execute({
+      'realm-url': TARGET_REALM,
       query: { filter: { type: { name: 'Issue' } } },
     });
 
-    assert.true(requests[0].url.startsWith(TARGET_REALM));
+    // The mock client hits the per-realm `_search` endpoint (the wire shape
+    // of the production federated-search path is covered separately by
+    // `factory-tool-executor.integration.test.ts > boxel-cli tool wire shape`).
+    assert.strictEqual(requests.length, 1, 'one search request emitted');
+    assert.true(
+      requests[0].url.startsWith(TARGET_REALM),
+      `request url should start with target realm, got ${requests[0].url}`,
+    );
   });
 });
 
@@ -821,7 +664,6 @@ module(
       assert.false(toolNames.includes('update_project'));
       assert.false(toolNames.includes('update_issue'));
       assert.false(toolNames.includes('create_knowledge'));
-      assert.true(toolNames.includes('write_file'));
       assert.true(toolNames.includes('run_command'));
     });
 
diff --git a/packages/software-factory/tests/factory-tool-executor.integration.test.ts b/packages/software-factory/tests/factory-tool-executor.integration.test.ts
index 57539a0e5f5..564125dcb3c 100644
--- a/packages/software-factory/tests/factory-tool-executor.integration.test.ts
+++ b/packages/software-factory/tests/factory-tool-executor.integration.test.ts
@@ -1,12 +1,44 @@
 import { createServer, type IncomingMessage, type Server } from 'node:http';
 import { module, test } from 'qunit';
 
+import { getToolDefinitions } from '@cardstack/boxel-cli/api';
 import { SupportedMimeType } from '@cardstack/runtime-common/supported-mime-type';
 
-import { ToolExecutor } from '../src/factory-tool-executor';
+import { adaptBoxelTool, type FactoryTool } from '../src/factory-tool-builder';
+import {
+  ToolExecutor,
+  type RealmSafetyConfig,
+} from '../src/factory-tool-executor';
 import { ToolRegistry } from '../src/factory-tool-registry';
 import { buildTestClient } from './helpers/test-client';
 
+import type { BoxelCLIClient } from '@cardstack/boxel-cli/api';
+
+/**
+ * Build a single boxel-cli FactoryTool wrapped with `enforceRealmSafety`,
+ * matching what `buildFactoryTools` does at runtime. Used by the
+ * realm-api integration tests that exercise wire shape through the
+ * agent-facing FactoryTool path.
+ */
+function buildBoxelFactoryTool(
+  toolName: string,
+  client: BoxelCLIClient,
+  safety: RealmSafetyConfig,
+  realmServerUrl: string,
+): FactoryTool {
+  let tools = getToolDefinitions(client, {
+    targetRealmUrl: safety.targetRealmUrl,
+    realmServerUrl,
+  });
+  let boxelTool = tools.find((t) => t.name === toolName);
+  if (!boxelTool) {
+    throw new Error(
+      `boxel-cli tool "${toolName}" not found in getToolDefinitions`,
+    );
+  }
+  return adaptBoxelTool(boxelTool, safety);
+}
+
 // ---------------------------------------------------------------------------
 // Test server helpers
 // ---------------------------------------------------------------------------
@@ -73,217 +105,211 @@ function stopServer(server: Server): Promise<void> {
 }
 
 // ---------------------------------------------------------------------------
-// Integration tests: realm-api tools against a real HTTP server
+// Integration tests: boxel-cli tool wire shape against a real HTTP server
 // ---------------------------------------------------------------------------
-
-module('factory-tool-executor integration > realm-api requests', function () {
-  // realm-read/realm-write/realm-delete are restricted to non-target
-  // realms (target-realm I/O goes through the workspace). Each test sets
-  // `targetRealmUrl` to a distinct path and whitelists a scratch realm
-  // via `allowedRealmPrefixes` so the tool's HTTP behavior can still be
-  // verified.
-  test('realm-read sends correct GET with Authorization and Accept headers', async function (assert) {
-    let captured: CapturedRequest | undefined;
-
-    let { server, origin } = await startTestServer((req, respond) => {
-      captured = req;
-      respond(200, { data: { id: 'Card/hello', type: 'card' } });
-    });
-
-    let scratchRealmUrl = `${origin}/user/scratch/`;
-    let targetRealmUrl = `${origin}/user/target/`;
-    let { client, cleanup } = buildTestClient({
-      realmUrl: scratchRealmUrl,
-      realmToken: 'Bearer realm-jwt-for-user',
-      realmServerUrl: `${origin}/`,
-      realmServerToken: 'Bearer realm-server-jwt',
-    });
-
-    try {
-      let registry = new ToolRegistry();
-      let executor = new ToolExecutor(registry, {
-        packageRoot: '/fake',
-        targetRealmUrl,
-        allowedRealmPrefixes: [`${origin}/user/scratch/`],
-        client,
+// Each test asserts the exact HTTP request the boxel-cli tool emits when the
+// factory invokes it via getToolDefinitions(). A regression like "we forgot
+// to send the Bearer token" or "we sent JSON instead of card-source" would
+// fail one of these tests with a clear diff.
+
+// Wire-shape coverage for realm-* tools comes from the
+// `boxel-cli tool wire shape` module below (which exercises
+// getToolDefinitions directly). Safety-guard coverage on top of that
+// path lives in factory-tool-executor.test.ts via the buildBoxelFactoryTool
+// helper. The previous `realm-api requests` module routed through
+// `executor.execute('realm-*', …)` — that dispatch path no longer exists.
+module(
+  'factory-tool-executor integration > boxel-cli tool wire shape',
+  function () {
+    test('realm_read_file sends GET with realm JWT and card-source Accept', async function (assert) {
+      let captured: CapturedRequest | undefined;
+      let { server, origin } = await startTestServer((req, respond) => {
+        captured = req;
+        respond(200, 'export class A {}', {
+          'Content-Type': SupportedMimeType.CardSource,
+        });
       });
 
-      let result = await executor.execute('realm-read', {
-        'realm-url': scratchRealmUrl,
-        path: 'Card/hello.gts',
+      let realmUrl = `${origin}/user/target/`;
+      let realmServerUrl = `${origin}/`;
+      let { client, cleanup } = buildTestClient({
+        realmUrl,
+        realmToken: 'Bearer realm-jwt-for-user',
+        realmServerUrl,
+        realmServerToken: 'Bearer realm-server-jwt',
       });
 
-      assert.strictEqual(result.exitCode, 0, 'exitCode is 0');
-      assert.strictEqual(captured!.method, 'GET');
-      assert.strictEqual(captured!.url, '/user/scratch/Card/hello.gts');
-      assert.strictEqual(
-        captured!.headers.authorization,
-        'Bearer realm-jwt-for-user',
-      );
-      assert.strictEqual(
-        captured!.headers.accept,
-        SupportedMimeType.CardSource,
-      );
-    } finally {
-      cleanup();
-      await stopServer(server);
-    }
-  });
-
-  test('realm-write sends correct POST with content and headers', async function (assert) {
-    let captured: CapturedRequest | undefined;
+      try {
+        let tools = getToolDefinitions(client, {
+          targetRealmUrl: realmUrl,
+          realmServerUrl,
+        });
+        let realmRead = tools.find((t) => t.name === 'realm_read_file')!;
 
-    let { server, origin } = await startTestServer((req, respond) => {
-      captured = req;
-      respond(200, { ok: true });
-    });
+        await realmRead.execute({
+          'realm-url': realmUrl,
+          path: 'Card/hello.gts',
+        });
 
-    let scratchRealmUrl = `${origin}/user/scratch/`;
-    let targetRealmUrl = `${origin}/user/target/`;
-    let { client, cleanup } = buildTestClient({
-      realmUrl: scratchRealmUrl,
-      realmToken: 'Bearer realm-jwt-for-user',
-      realmServerUrl: `${origin}/`,
-      realmServerToken: 'Bearer realm-server-jwt',
+        assert.ok(captured, 'request reached the server');
+        assert.strictEqual(captured!.method, 'GET');
+        assert.strictEqual(captured!.url, '/user/target/Card/hello.gts');
+        assert.strictEqual(
+          captured!.headers.authorization,
+          'Bearer realm-jwt-for-user',
+        );
+        assert.strictEqual(
+          captured!.headers.accept,
+          SupportedMimeType.CardSource,
+        );
+        assert.strictEqual(captured!.body, '');
+      } finally {
+        cleanup();
+        await stopServer(server);
+      }
     });
 
-    try {
-      let registry = new ToolRegistry();
-      let executor = new ToolExecutor(registry, {
-        packageRoot: '/fake',
-        targetRealmUrl,
-        allowedRealmPrefixes: [`${origin}/user/scratch/`],
-        client,
+    test('realm_write_file sends POST with content body and card-source headers', async function (assert) {
+      let captured: CapturedRequest | undefined;
+      let { server, origin } = await startTestServer((req, respond) => {
+        captured = req;
+        respond(200, { ok: true });
       });
 
-      let result = await executor.execute('realm-write', {
-        'realm-url': scratchRealmUrl,
-        path: 'CardDef/my-card.gts',
-        content: 'export class MyCard extends CardDef {}',
+      let realmUrl = `${origin}/user/target/`;
+      let realmServerUrl = `${origin}/`;
+      let { client, cleanup } = buildTestClient({
+        realmUrl,
+        realmToken: 'Bearer realm-jwt-for-user',
+        realmServerUrl,
+        realmServerToken: 'Bearer realm-server-jwt',
       });
 
-      assert.strictEqual(result.exitCode, 0);
-      assert.strictEqual(captured!.method, 'POST');
-      assert.strictEqual(captured!.url, '/user/scratch/CardDef/my-card.gts');
-      assert.strictEqual(
-        captured!.headers.authorization,
-        'Bearer realm-jwt-for-user',
-      );
-      assert.strictEqual(
-        captured!.headers['content-type'],
-        SupportedMimeType.CardSource,
-      );
-      assert.strictEqual(
-        captured!.body,
-        'export class MyCard extends CardDef {}',
-      );
-    } finally {
-      cleanup();
-      await stopServer(server);
-    }
-  });
-
-  test('realm-delete sends correct DELETE with Authorization header', async function (assert) {
-    let captured: CapturedRequest | undefined;
+      try {
+        let tools = getToolDefinitions(client, {
+          targetRealmUrl: realmUrl,
+          realmServerUrl,
+        });
+        let realmWrite = tools.find((t) => t.name === 'realm_write_file')!;
+        let content = 'export class MyCard extends CardDef {}';
 
-    let { server, origin } = await startTestServer((req, respond) => {
-      captured = req;
-      respond(204, null);
-    });
+        await realmWrite.execute({
+          'realm-url': realmUrl,
+          path: 'CardDef/my-card.gts',
+          content,
+        });
 
-    let scratchRealmUrl = `${origin}/user/scratch/`;
-    let targetRealmUrl = `${origin}/user/target/`;
-    let { client, cleanup } = buildTestClient({
-      realmUrl: scratchRealmUrl,
-      realmToken: 'Bearer realm-jwt-for-user',
-      realmServerUrl: `${origin}/`,
-      realmServerToken: 'Bearer realm-server-jwt',
+        assert.ok(captured, 'request reached the server');
+        assert.strictEqual(captured!.method, 'POST');
+        assert.strictEqual(captured!.url, '/user/target/CardDef/my-card.gts');
+        assert.strictEqual(
+          captured!.headers.authorization,
+          'Bearer realm-jwt-for-user',
+        );
+        assert.strictEqual(
+          captured!.headers['content-type'],
+          SupportedMimeType.CardSource,
+        );
+        assert.strictEqual(captured!.body, content);
+      } finally {
+        cleanup();
+        await stopServer(server);
+      }
     });
 
-    try {
-      let registry = new ToolRegistry();
-      let executor = new ToolExecutor(registry, {
-        packageRoot: '/fake',
-        targetRealmUrl,
-        allowedRealmPrefixes: [`${origin}/user/scratch/`],
-        client,
+    test('realm_delete_file sends DELETE with realm JWT', async function (assert) {
+      let captured: CapturedRequest | undefined;
+      let { server, origin } = await startTestServer((req, respond) => {
+        captured = req;
+        respond(200, { ok: true });
       });
 
-      let result = await executor.execute('realm-delete', {
-        'realm-url': scratchRealmUrl,
-        path: 'Card/old-card.json',
+      let realmUrl = `${origin}/user/target/`;
+      let realmServerUrl = `${origin}/`;
+      let { client, cleanup } = buildTestClient({
+        realmUrl,
+        realmToken: 'Bearer realm-jwt-for-user',
+        realmServerUrl,
+        realmServerToken: 'Bearer realm-server-jwt',
       });
 
-      assert.strictEqual(result.exitCode, 0);
-      assert.strictEqual(captured!.method, 'DELETE');
-      assert.strictEqual(captured!.url, '/user/scratch/Card/old-card.json');
-      assert.strictEqual(
-        captured!.headers.authorization,
-        'Bearer realm-jwt-for-user',
-      );
-    } finally {
-      cleanup();
-      await stopServer(server);
-    }
-  });
-
-  test('realm-search sends correct QUERY to _federated-search with JSON body', async function (assert) {
-    let captured: CapturedRequest | undefined;
+      try {
+        let tools = getToolDefinitions(client, {
+          targetRealmUrl: realmUrl,
+          realmServerUrl,
+        });
+        let realmDelete = tools.find((t) => t.name === 'realm_delete_file')!;
 
-    let { server, origin } = await startTestServer((req, respond) => {
-      captured = req;
-      respond(200, { data: [] });
-    });
+        await realmDelete.execute({
+          'realm-url': realmUrl,
+          path: 'Card/old.json',
+        });
 
-    let realmUrl = `${origin}/user/target/`;
-    let { client, cleanup } = buildTestClient({
-      realmUrl,
-      realmToken: 'Bearer realm-jwt-for-user',
-      realmServerUrl: `${origin}/`,
-      realmServerToken: 'Bearer realm-server-jwt',
+        assert.ok(captured, 'request reached the server');
+        assert.strictEqual(captured!.method, 'DELETE');
+        assert.strictEqual(captured!.url, '/user/target/Card/old.json');
+        assert.strictEqual(
+          captured!.headers.authorization,
+          'Bearer realm-jwt-for-user',
+        );
+        assert.strictEqual(captured!.body, '');
+      } finally {
+        cleanup();
+        await stopServer(server);
+      }
     });
 
-    try {
-      let registry = new ToolRegistry();
-      let executor = new ToolExecutor(registry, {
-        packageRoot: '/fake',
-        targetRealmUrl: realmUrl,
-        client,
+    test('realm_search sends QUERY to _federated-search with server JWT and realms array', async function (assert) {
+      let captured: CapturedRequest | undefined;
+      let { server, origin } = await startTestServer((req, respond) => {
+        captured = req;
+        respond(200, { data: [] });
       });
 
-      let query = JSON.stringify({
-        filter: {
-          type: { module: 'https://example.test/issue', name: 'Issue' },
-        },
+      let realmUrl = `${origin}/user/target/`;
+      let realmServerUrl = `${origin}/`;
+      let { client, cleanup } = buildTestClient({
+        realmUrl,
+        realmToken: 'Bearer realm-jwt-for-user',
+        realmServerUrl,
+        realmServerToken: 'Bearer realm-server-jwt',
       });
 
-      let result = await executor.execute('realm-search', {
-        'realm-url': realmUrl,
-        query,
-      });
+      try {
+        let tools = getToolDefinitions(client, {
+          targetRealmUrl: realmUrl,
+          realmServerUrl,
+        });
+        let realmSearch = tools.find((t) => t.name === 'realm_search')!;
+        let query = { filter: { type: { name: 'Issue' } } };
 
-      assert.strictEqual(result.exitCode, 0);
-      assert.strictEqual(captured!.method, 'QUERY');
-      assert.strictEqual(captured!.url, '/_federated-search');
-      assert.strictEqual(
-        captured!.headers.authorization,
-        'Bearer realm-server-jwt',
-      );
-      assert.strictEqual(captured!.headers.accept, SupportedMimeType.CardJson);
-      assert.strictEqual(
-        captured!.headers['content-type'],
-        SupportedMimeType.JSON,
-      );
-      assert.deepEqual(JSON.parse(captured!.body), {
-        realms: [realmUrl],
-        ...JSON.parse(query),
-      });
-    } finally {
-      cleanup();
-      await stopServer(server);
-    }
-  });
-});
+        await realmSearch.execute({ 'realm-url': realmUrl, query });
+
+        assert.ok(captured, 'request reached the server');
+        assert.strictEqual(captured!.method, 'QUERY');
+        assert.strictEqual(captured!.url, '/_federated-search');
+        assert.strictEqual(
+          captured!.headers.authorization,
+          'Bearer realm-server-jwt',
+        );
+        assert.strictEqual(
+          captured!.headers['content-type'],
+          'application/json',
+        );
+
+        let parsed = JSON.parse(captured!.body) as {
+          realms: string[];
+          filter: unknown;
+        };
+        assert.deepEqual(parsed.realms, [realmUrl], 'body.realms = [realmUrl]');
+        assert.deepEqual(parsed.filter, query.filter, 'query merged into body');
+      } finally {
+        cleanup();
+        await stopServer(server);
+      }
+    });
+  },
+);
 
 // ---------------------------------------------------------------------------
 // Integration tests: safety constraints prevent requests from reaching server
@@ -392,15 +418,17 @@ module('factory-tool-executor integration > safety constraints', function () {
     });
 
     try {
-      let registry = new ToolRegistry();
-      let executor = new ToolExecutor(registry, {
-        packageRoot: '/fake',
-        targetRealmUrl: `${origin}/user/target/`,
+      let realmRead = buildBoxelFactoryTool(
+        'realm_read_file',
         client,
-      });
+        {
+          targetRealmUrl: `${origin}/user/target/`,
+        },
+        `${origin}/`,
+      );
 
       try {
-        await executor.execute('realm-read', {
+        await realmRead.execute({
           'realm-url': 'https://evil.example.test/hacker/realm/',
           path: 'secrets.json',
         });
diff --git a/packages/software-factory/tests/factory-tool-executor.spec.ts b/packages/software-factory/tests/factory-tool-executor.spec.ts
index e8735f7a0a2..234ceec3ef8 100644
--- a/packages/software-factory/tests/factory-tool-executor.spec.ts
+++ b/packages/software-factory/tests/factory-tool-executor.spec.ts
@@ -14,9 +14,47 @@ import { rri } from '@cardstack/runtime-common/card-reference-resolver';
 import { test } from './fixtures';
 import { expect } from '@playwright/test';
 
-import { ToolExecutor, ToolNotFoundError } from '../src/factory-tool-executor';
+import {
+  ToolExecutor,
+  ToolNotFoundError,
+  type RealmSafetyConfig,
+} from '../src/factory-tool-executor';
 import { ToolRegistry } from '../src/factory-tool-registry';
-import { buildFactoryTools } from '../src/factory-tool-builder';
+
+import {
+  adaptBoxelTool,
+  buildFactoryTools,
+  type FactoryTool,
+} from '../src/factory-tool-builder';
+import {
+  getToolDefinitions,
+  type BoxelCLIClient,
+} from '@cardstack/boxel-cli/api';
+
+/**
+ * Build a single boxel-cli FactoryTool wrapped with `enforceRealmSafety`,
+ * matching what `buildFactoryTools` does at runtime. Used by the realm-*
+ * Playwright tests — those tools live in boxel-cli's getToolDefinitions
+ * and never go through the executor's dispatch.
+ */
+function buildBoxelFactoryTool(
+  toolName: string,
+  client: BoxelCLIClient,
+  safety: RealmSafetyConfig,
+  realmServerUrl: string,
+): FactoryTool {
+  let tools = getToolDefinitions(client, {
+    targetRealmUrl: safety.targetRealmUrl,
+    realmServerUrl,
+  });
+  let boxelTool = tools.find((t) => t.name === toolName);
+  if (!boxelTool) {
+    throw new Error(
+      `boxel-cli tool "${toolName}" not found in getToolDefinitions`,
+    );
+  }
+  return adaptBoxelTool(boxelTool, safety);
+}
 import { fetchCardTypeSchema } from '../src/darkfactory-schemas';
 import {
   baseRealmURLFor,
@@ -26,8 +64,9 @@ import {
 } from '../src/harness/shared';
 import { buildTestClient } from './helpers/test-client';
 import { createTestWorkspace } from './helpers/workspace-fixture';
+import { readCard, writeCard } from '../src/workspace-fs';
 
-test('realm-search returns results from the test realm', async ({ realm }) => {
+test('realm_search returns results from the test realm', async ({ realm }) => {
   let { client, cleanup } = buildTestClient({
     realmUrl: realm.realmURL.href,
     realmToken: `Bearer ${realm.ownerBearerToken}`,
@@ -36,15 +75,17 @@ test('realm-search returns results from the test realm', async ({ realm }) => {
   });
 
   try {
-    let registry = new ToolRegistry();
-    let executor = new ToolExecutor(registry, {
-      packageRoot: process.cwd(),
-      targetRealmUrl: realm.realmURL.href,
-      allowedRealmPrefixes: [realm.realmURL.origin + '/'],
+    let realmSearch = buildBoxelFactoryTool(
+      'realm_search',
       client,
-    });
+      {
+        targetRealmUrl: realm.realmURL.href,
+        allowedRealmPrefixes: [realm.realmURL.origin + '/'],
+      },
+      realm.realmServerURL.href,
+    );
 
-    let result = await executor.execute('realm-search', {
+    let output = (await realmSearch.execute({
       'realm-url': realm.realmURL.href,
       query: JSON.stringify({
         filter: {
@@ -55,10 +96,9 @@ test('realm-search returns results from the test realm', async ({ realm }) => {
         },
         page: { size: 1 },
       }),
-    });
+    })) as { data?: unknown[]; error?: string };
 
-    expect(result.exitCode).toBe(0);
-    let output = result.output as { data?: unknown[] };
+    expect(output.error).toBeUndefined();
     expect(Array.isArray(output.data)).toBe(true);
   } finally {
     cleanup();
@@ -95,9 +135,6 @@ test('unregistered tool is rejected without reaching the server', async ({
 // Factory tool (card write) tests against live realm
 // ---------------------------------------------------------------------------
 
-import type { FactoryTool } from '../src/factory-tool-builder';
-import type { BoxelCLIClient } from '@cardstack/boxel-cli/api';
-
 type CardWriteResult = { ok: boolean; error?: string };
 type CardReadResult = { ok: boolean; document?: Record<string, unknown> };
 
@@ -114,6 +151,7 @@ async function buildToolsForRealm(
   let executor = new ToolExecutor(registry, {
     packageRoot: process.cwd(),
     targetRealmUrl: realm.realmURL.href,
+    realmServerUrl: realm.realmServerURL.href,
     allowedRealmPrefixes: [realm.realmURL.origin + '/'],
     client,
   });
@@ -187,7 +225,6 @@ test('update_project writes and reads back a project card', async ({
     await client.pull(realm.realmURL.href, workspace.dir);
     let tools = await buildToolsForRealm(realm, client, workspace.dir);
     let updateProject = tools.find((t) => t.name === 'update_project')!;
-    let readFile = tools.find((t) => t.name === 'read_file')!;
 
     expect(updateProject).toBeDefined();
 
@@ -201,9 +238,10 @@ test('update_project writes and reads back a project card', async ({
 
     expect(writeResult.ok).toBe(true);
 
-    let readResult = (await readFile.execute({
-      path: 'Projects/tool-test-project.json',
-    })) as CardReadResult;
+    let readResult = (await readCard(
+      workspace.dir,
+      'Projects/tool-test-project.json',
+    )) as CardReadResult;
 
     expect(readResult.ok).toBe(true);
     let doc = readResult.document as unknown as LooseSingleCardDocument;
@@ -228,7 +266,6 @@ test('update_issue writes and reads back an issue card', async ({ realm }) => {
     await client.pull(realm.realmURL.href, workspace.dir);
     let tools = await buildToolsForRealm(realm, client, workspace.dir);
     let updateIssue = tools.find((t) => t.name === 'update_issue')!;
-    let readFile = tools.find((t) => t.name === 'read_file')!;
 
     expect(updateIssue).toBeDefined();
 
@@ -243,9 +280,10 @@ test('update_issue writes and reads back an issue card', async ({ realm }) => {
 
     expect(writeResult.ok).toBe(true);
 
-    let readResult = (await readFile.execute({
-      path: 'Issues/tool-test-issue.json',
-    })) as CardReadResult;
+    let readResult = (await readCard(
+      workspace.dir,
+      'Issues/tool-test-issue.json',
+    )) as CardReadResult;
 
     expect(readResult.ok).toBe(true);
     let doc = readResult.document as unknown as LooseSingleCardDocument;
@@ -272,14 +310,12 @@ test('add_comment appends a comment to an existing issue without changing other
     let workspace = createTestWorkspace();
     await client.pull(realm.realmURL.href, workspace.dir);
     let tools = await buildToolsForRealm(realm, client, workspace.dir);
-    let writeFile = tools.find((t) => t.name === 'write_file')!;
     let addComment = tools.find((t) => t.name === 'add_comment')!;
-    let readFileTool = tools.find((t) => t.name === 'read_file')!;
 
     expect(addComment).toBeDefined();
 
-    // Create an issue via write_file (descriptions are set at creation time,
-    // not via update_issue which strips them)
+    // Pre-seed an issue directly into the workspace (descriptions are set
+    // at creation time, not via update_issue which strips them).
     let darkfactoryModule = `${realm.realmServerURL.href}software-factory/darkfactory`;
     let issueDoc = {
       data: {
@@ -295,10 +331,11 @@ test('add_comment appends a comment to an existing issue without changing other
         },
       },
     };
-    let createResult = (await writeFile.execute({
-      path: 'Issues/comment-test-issue.json',
-      content: JSON.stringify(issueDoc, null, 2),
-    })) as CardWriteResult;
+    let createResult = (await writeCard(
+      workspace.dir,
+      'Issues/comment-test-issue.json',
+      JSON.stringify(issueDoc, null, 2),
+    )) as CardWriteResult;
 
     expect(createResult.ok).toBe(true);
 
@@ -312,9 +349,10 @@ test('add_comment appends a comment to an existing issue without changing other
     expect(commentResult.ok).toBe(true);
 
     // Read back and verify
-    let readResult = (await readFileTool.execute({
-      path: 'Issues/comment-test-issue.json',
-    })) as CardReadResult;
+    let readResult = (await readCard(
+      workspace.dir,
+      'Issues/comment-test-issue.json',
+    )) as CardReadResult;
 
     expect(readResult.ok).toBe(true);
     let doc = readResult.document as unknown as LooseSingleCardDocument;
@@ -356,7 +394,6 @@ test('create_knowledge writes and reads back a knowledge article', async ({
     await client.pull(realm.realmURL.href, workspace.dir);
     let tools = await buildToolsForRealm(realm, client, workspace.dir);
     let createKnowledge = tools.find((t) => t.name === 'create_knowledge')!;
-    let readFile = tools.find((t) => t.name === 'read_file')!;
 
     expect(createKnowledge).toBeDefined();
 
@@ -370,9 +407,10 @@ test('create_knowledge writes and reads back a knowledge article', async ({
 
     expect(writeResult.ok).toBe(true);
 
-    let readResult = (await readFile.execute({
-      path: 'Knowledge Articles/tool-test-article.json',
-    })) as CardReadResult;
+    let readResult = (await readCard(
+      workspace.dir,
+      'Knowledge Articles/tool-test-article.json',
+    )) as CardReadResult;
 
     expect(readResult.ok).toBe(true);
     let doc = readResult.document as unknown as LooseSingleCardDocument;
@@ -399,7 +437,6 @@ test('create_catalog_spec writes and reads back a Spec card', async ({
     let createCatalogSpec = tools.find(
       (t) => t.name === 'create_catalog_spec',
     )!;
-    let readFile = tools.find((t) => t.name === 'read_file')!;
 
     expect(createCatalogSpec).toBeDefined();
 
@@ -414,9 +451,10 @@ test('create_catalog_spec writes and reads back a Spec card', async ({
 
     expect(writeResult.ok).toBe(true);
 
-    let readResult = (await readFile.execute({
-      path: 'Spec/tool-test-spec.json',
-    })) as CardReadResult;
+    let readResult = (await readCard(
+      workspace.dir,
+      'Spec/tool-test-spec.json',
+    )) as CardReadResult;
 
     expect(readResult.ok).toBe(true);
     let doc = readResult.document as unknown as LooseSingleCardDocument;
@@ -433,12 +471,12 @@ test('create_catalog_spec writes and reads back a Spec card', async ({
 });
 
 // ---------------------------------------------------------------------------
-// realm-search with pre-seeded fixture data
+// realm_search with pre-seeded fixture data
 // The darkfactory-adopter fixture has Project and Issue cards with
 // distinct types — we search for each and verify the filter works.
 // ---------------------------------------------------------------------------
 
-test.describe('realm-search with seeded fixture data', () => {
+test.describe('realm_search with seeded fixture data', () => {
   // Uses default darkfactory-adopter fixture (shared mode for speed)
 
   test('search by type returns matching cards and excludes non-matching types', async ({
@@ -455,17 +493,16 @@ test.describe('realm-search with seeded fixture data', () => {
       // The darkfactory-adopter fixture type module uses a placeholder URL
       // that gets remapped at runtime. Discover the live module URL by
       // reading a known card and extracting its adoptsFrom module.
-      let registry = new ToolRegistry();
-      let executor = new ToolExecutor(registry, {
-        packageRoot: process.cwd(),
-        targetRealmUrl: realm.realmURL.href,
-        allowedRealmPrefixes: [realm.realmURL.origin + '/'],
+      let realmSearch = buildBoxelFactoryTool(
+        'realm_search',
         client,
-      });
+        {
+          targetRealmUrl: realm.realmURL.href,
+          allowedRealmPrefixes: [realm.realmURL.origin + '/'],
+        },
+        realm.realmServerURL.href,
+      );
 
-      // Discover the darkfactory module URL by reading a known card's
-      // adoptsFrom via the BoxelCLIClient — this is setup for the
-      // realm-search assertions below.
       let projectRead = await client.read(
         realm.realmURL.href,
         'project-demo.json',
@@ -477,22 +514,19 @@ test.describe('realm-search with seeded fixture data', () => {
       let darkfactoryModule = projectDoc.data.meta.adoptsFrom.module;
 
       // Search for Project cards — should find at least project-demo
-      let projectResult = await executor.execute('realm-search', {
+      let projectOutput = (await realmSearch.execute({
         'realm-url': realm.realmURL.href,
         query: JSON.stringify({
           filter: {
             type: { module: darkfactoryModule, name: 'Project' },
           },
         }),
-      });
+      })) as { data?: { id: string }[]; error?: string };
 
       expect(
-        projectResult.exitCode,
-        `project search failed: ${JSON.stringify(projectResult.output)}`,
-      ).toBe(0);
-      let projectOutput = projectResult.output as {
-        data?: { id: string }[];
-      };
+        projectOutput.error,
+        `project search failed: ${JSON.stringify(projectOutput)}`,
+      ).toBeUndefined();
       expect(
         (projectOutput.data?.length ?? 0) > 0,
         'should find at least one Project card',
@@ -500,18 +534,15 @@ test.describe('realm-search with seeded fixture data', () => {
       let projectIds = (projectOutput.data ?? []).map((d) => d.id);
 
       // Verify no Issue cards leak into the Project results
-      let issueResult = await executor.execute('realm-search', {
+      let issueOutput = (await realmSearch.execute({
         'realm-url': realm.realmURL.href,
         query: JSON.stringify({
           filter: {
             type: { module: darkfactoryModule, name: 'Issue' },
           },
         }),
-      });
-      expect(issueResult.exitCode).toBe(0);
-      let issueOutput = issueResult.output as {
-        data?: { id: string }[];
-      };
+      })) as { data?: { id: string }[]; error?: string };
+      expect(issueOutput.error).toBeUndefined();
       let issueIds = (issueOutput.data ?? []).map((d) => d.id);
 
       // Project and Issue result sets must be disjoint
@@ -528,10 +559,10 @@ test.describe('realm-search with seeded fixture data', () => {
 });
 
 // ---------------------------------------------------------------------------
-// realm-search on a private realm: verifies auth is enforced
+// realm_search on a private realm: verifies auth is enforced
 // ---------------------------------------------------------------------------
 
-test.describe('realm-search on a private realm', () => {
+test.describe('realm_search on a private realm', () => {
   test.use({ realmServerMode: 'isolated' });
   test.use({
     realmPermissions: {
@@ -551,17 +582,7 @@ test.describe('realm-search on a private realm', () => {
     });
 
     try {
-      let registry = new ToolRegistry();
-
-      // Discover the live module URL from the fixture data
-      let ownerExecutor = new ToolExecutor(registry, {
-        packageRoot: process.cwd(),
-        targetRealmUrl: realm.realmURL.href,
-        allowedRealmPrefixes: [realm.realmURL.origin + '/'],
-        client: ownerSetup.client,
-      });
-
-      // Discover the module URL via the client for the search assertions below.
+      // Discover the live module URL from the fixture data via the client.
       let projectRead = await ownerSetup.client.read(
         realm.realmURL.href,
         'project-demo.json',
@@ -582,16 +603,25 @@ test.describe('realm-search on a private realm', () => {
       });
 
       // Authenticated search with owner token — should succeed
-      let authedResult = await ownerExecutor.execute('realm-search', {
+      let ownerSearch = buildBoxelFactoryTool(
+        'realm_search',
+        ownerSetup.client,
+        {
+          targetRealmUrl: realm.realmURL.href,
+          allowedRealmPrefixes: [realm.realmURL.origin + '/'],
+        },
+        realm.realmServerURL.href,
+      );
+
+      let authedOutput = (await ownerSearch.execute({
         'realm-url': realm.realmURL.href,
         query: searchQuery,
-      });
+      })) as { data?: unknown[]; error?: string };
 
       expect(
-        authedResult.exitCode,
-        `authenticated search failed: ${JSON.stringify(authedResult.output)}`,
-      ).toBe(0);
-      let authedOutput = authedResult.output as { data?: unknown[] };
+        authedOutput.error,
+        `authenticated search failed: ${JSON.stringify(authedOutput)}`,
+      ).toBeUndefined();
       expect(
         (authedOutput.data?.length ?? 0) > 0,
         'authenticated search should return results',
@@ -615,25 +645,22 @@ test.describe('realm-search on a private realm', () => {
       });
 
       try {
-        let unauthorizedExecutor = new ToolExecutor(registry, {
-          packageRoot: process.cwd(),
-          targetRealmUrl: realm.realmURL.href,
-          allowedRealmPrefixes: [realm.realmURL.origin + '/'],
-          client: unauthorizedSetup.client,
-        });
-
-        let unauthorizedResult = await unauthorizedExecutor.execute(
-          'realm-search',
+        let unauthorizedSearch = buildBoxelFactoryTool(
+          'realm_search',
+          unauthorizedSetup.client,
           {
-            'realm-url': realm.realmURL.href,
-            query: searchQuery,
+            targetRealmUrl: realm.realmURL.href,
+            allowedRealmPrefixes: [realm.realmURL.origin + '/'],
           },
+          realm.realmServerURL.href,
         );
 
-        expect(unauthorizedResult.exitCode).toBe(1);
-        let unauthorizedOutput = unauthorizedResult.output as {
-          status?: number;
-        };
+        let unauthorizedOutput = (await unauthorizedSearch.execute({
+          'realm-url': realm.realmURL.href,
+          query: searchQuery,
+        })) as { data?: unknown[]; error?: string; status?: number };
+
+        expect(unauthorizedOutput.error).toBeDefined();
         expect(unauthorizedOutput.status).toBe(403);
       } finally {
         unauthorizedSetup.cleanup();
diff --git a/packages/software-factory/tests/factory-tool-executor.test.ts b/packages/software-factory/tests/factory-tool-executor.test.ts
index 9797d98e640..8e7999e1fb9 100644
--- a/packages/software-factory/tests/factory-tool-executor.test.ts
+++ b/packages/software-factory/tests/factory-tool-executor.test.ts
@@ -1,16 +1,18 @@
 import { module, test } from 'qunit';
 
+import { getToolDefinitions } from '@cardstack/boxel-cli/api';
 import { SupportedMimeType } from '@cardstack/runtime-common/supported-mime-type';
 
-import type { ToolResult } from '../src/factory-agent';
+import { adaptBoxelTool } from '../src/factory-tool-builder';
 import {
   ToolExecutor,
   ToolNotFoundError,
   ToolSafetyError,
-  composeBoxelCliInvocation,
-  type ToolExecutionLogEntry,
+  enforceRealmSafety,
+  type RealmSafetyConfig,
   type ToolExecutorConfig,
 } from '../src/factory-tool-executor';
+import type { FactoryTool } from '../src/factory-tool-builder';
 import { ToolRegistry } from '../src/factory-tool-registry';
 import { createMockClient } from './helpers/mock-client';
 
@@ -18,13 +20,17 @@ import { createMockClient } from './helpers/mock-client';
 // Helpers
 // ---------------------------------------------------------------------------
 
+const TEST_TARGET_REALM = 'https://realms.example.test/user/target/';
+const TEST_REALM_SERVER = 'https://realms.example.test/';
+
 function makeConfig(
   overrides?: Partial<ToolExecutorConfig> & { fetch?: typeof globalThis.fetch },
 ): ToolExecutorConfig {
   let { fetch: fetchOverride, client, ...rest } = overrides ?? {};
   return {
     packageRoot: '/fake/software-factory',
-    targetRealmUrl: 'https://realms.example.test/user/target/',
+    targetRealmUrl: TEST_TARGET_REALM,
+    realmServerUrl: TEST_REALM_SERVER,
     client:
       client ??
       createMockClient(fetchOverride ? { fetch: fetchOverride } : undefined),
@@ -32,14 +38,53 @@ function makeConfig(
   };
 }
 
+/**
+ * Build a single boxel-cli FactoryTool wrapped with `enforceRealmSafety`,
+ * mirroring what `buildFactoryTools` does at runtime. Used by tests that
+ * exercise realm-* tools — those tools live in boxel-cli's
+ * getToolDefinitions and are never dispatched through the executor.
+ */
+function buildBoxelFactoryTool(
+  toolName: string,
+  config: ToolExecutorConfig,
+): FactoryTool {
+  let safety: RealmSafetyConfig = {
+    targetRealmUrl: config.targetRealmUrl,
+    sourceRealmUrl: config.sourceRealmUrl,
+    allowedRealmPrefixes: config.allowedRealmPrefixes,
+  };
+  let boxelTools = getToolDefinitions(config.client, {
+    targetRealmUrl: config.targetRealmUrl,
+    realmServerUrl: config.realmServerUrl ?? TEST_REALM_SERVER,
+  });
+  let boxelTool = boxelTools.find((t) => t.name === toolName);
+  if (!boxelTool) {
+    throw new Error(
+      `boxel-cli tool "${toolName}" not found in getToolDefinitions`,
+    );
+  }
+  return adaptBoxelTool(boxelTool, safety);
+}
+
+function createMockFetch(
+  status: number,
+  body: unknown,
+): typeof globalThis.fetch {
+  return (async () => {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: { 'Content-Type': SupportedMimeType.JSON },
+    });
+  }) as typeof globalThis.fetch;
+}
+
 // ---------------------------------------------------------------------------
-// Unregistered tool rejection
+// Unregistered tool rejection (executor scope: script + boxel-cli subprocess)
 // ---------------------------------------------------------------------------
 
 module('factory-tool-executor > unregistered tool rejection', function () {
   test('rejects invoke_tool with empty tool name', async function (assert) {
-    let registry = new ToolRegistry();
-    let executor = new ToolExecutor(registry, makeConfig());
+    let executor = new ToolExecutor(new ToolRegistry(), makeConfig());
 
     try {
       await executor.execute('');
@@ -50,8 +95,7 @@ module('factory-tool-executor > unregistered tool rejection', function () {
   });
 
   test('rejects unregistered tool', async function (assert) {
-    let registry = new ToolRegistry();
-    let executor = new ToolExecutor(registry, makeConfig());
+    let executor = new ToolExecutor(new ToolRegistry(), makeConfig());
 
     try {
       await executor.execute('rm-rf-everything');
@@ -64,13 +108,12 @@ module('factory-tool-executor > unregistered tool rejection', function () {
 });
 
 // ---------------------------------------------------------------------------
-// Argument validation
+// Argument validation (executor scope: script + boxel-cli subprocess)
 // ---------------------------------------------------------------------------
 
 module('factory-tool-executor > argument validation', function () {
   test('rejects missing required arguments', async function (assert) {
-    let registry = new ToolRegistry();
-    let executor = new ToolExecutor(registry, makeConfig());
+    let executor = new ToolExecutor(new ToolRegistry(), makeConfig());
 
     try {
       await executor.execute('search-realm', {});
@@ -83,393 +126,287 @@ module('factory-tool-executor > argument validation', function () {
 });
 
 // ---------------------------------------------------------------------------
-// Safety: source realm protection
+// Source / allowed realm protection — script tools (go through the executor)
 // ---------------------------------------------------------------------------
 
-module('factory-tool-executor > source realm protection', function () {
-  test('rejects tool targeting source realm', async function (assert) {
-    let registry = new ToolRegistry();
-    let executor = new ToolExecutor(
-      registry,
-      makeConfig({
-        sourceRealmUrl: 'https://realms.example.test/user/source/',
-      }),
-    );
+module(
+  'factory-tool-executor > source realm protection (script tools)',
+  function () {
+    test('rejects script tool targeting source realm', async function (assert) {
+      let executor = new ToolExecutor(
+        new ToolRegistry(),
+        makeConfig({
+          sourceRealmUrl: 'https://realms.example.test/user/source/',
+        }),
+      );
 
-    try {
-      await executor.execute('search-realm', {
-        realm: 'https://realms.example.test/user/source/',
-      });
-      assert.ok(false, 'should have thrown');
-    } catch (err) {
-      assert.true(err instanceof ToolSafetyError);
-      assert.true((err as Error).message.includes('source realm'));
-    }
-  });
+      try {
+        await executor.execute('search-realm', {
+          realm: 'https://realms.example.test/user/source/',
+        });
+        assert.ok(false, 'should have thrown');
+      } catch (err) {
+        assert.true(err instanceof ToolSafetyError);
+        assert.true((err as Error).message.includes('source realm'));
+      }
+    });
 
-  test('rejects source realm without trailing slash', async function (assert) {
-    let registry = new ToolRegistry();
-    let executor = new ToolExecutor(
-      registry,
-      makeConfig({
-        sourceRealmUrl: 'https://realms.example.test/user/source/',
-      }),
-    );
+    test('rejects source realm without trailing slash', async function (assert) {
+      let executor = new ToolExecutor(
+        new ToolRegistry(),
+        makeConfig({
+          sourceRealmUrl: 'https://realms.example.test/user/source/',
+        }),
+      );
 
-    try {
-      await executor.execute('search-realm', {
-        realm: 'https://realms.example.test/user/source',
-      });
-      assert.ok(false, 'should have thrown');
-    } catch (err) {
-      assert.true(err instanceof ToolSafetyError);
-    }
-  });
+      try {
+        await executor.execute('search-realm', {
+          realm: 'https://realms.example.test/user/source',
+        });
+        assert.ok(false, 'should have thrown');
+      } catch (err) {
+        assert.true(err instanceof ToolSafetyError);
+      }
+    });
 
-  test('allows tool targeting target realm', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      sourceRealmUrl: 'https://realms.example.test/user/source/',
-      fetch: createMockFetch(200, { data: [] }),
+    test('rejects script tool targeting unknown realm URL', async function (assert) {
+      let executor = new ToolExecutor(new ToolRegistry(), makeConfig());
+
+      try {
+        await executor.execute('search-realm', {
+          realm: 'https://evil.example.test/hacker/realm/',
+        });
+        assert.ok(false, 'should have thrown');
+      } catch (err) {
+        assert.true(err instanceof ToolSafetyError);
+        assert.true((err as Error).message.includes('not in the allowed list'));
+      }
     });
-    let executor = new ToolExecutor(registry, config);
+  },
+);
 
-    let result = await executor.execute('realm-search', {
-      'realm-url': 'https://realms.example.test/user/target/',
-      query: JSON.stringify({ filter: { type: { name: 'Issue' } } }),
+// ---------------------------------------------------------------------------
+// Realm-targeting safety on boxel-cli FactoryTools — applies inside
+// `adaptBoxelTool` via the standalone `enforceRealmSafety` function.
+// ---------------------------------------------------------------------------
+
+module(
+  'factory-tool-executor > realm safety guard on boxel-cli tools',
+  function () {
+    test('rejects realm_read_file targeting the target realm (workspace-only)', async function (assert) {
+      let config = makeConfig();
+      let realmRead = buildBoxelFactoryTool('realm_read_file', config);
+
+      try {
+        await realmRead.execute({
+          'realm-url': TEST_TARGET_REALM,
+          path: 'foo.json',
+        });
+        assert.ok(false, 'should have thrown');
+      } catch (err) {
+        assert.true(err instanceof ToolSafetyError);
+        assert.true(
+          (err as Error).message.includes('cannot target the target realm'),
+          `error should mention target-realm rejection, got: ${(err as Error).message}`,
+        );
+      }
     });
 
-    assert.strictEqual(result.exitCode, 0);
-  });
+    test('rejects realm_write_file targeting the target realm', async function (assert) {
+      let config = makeConfig();
+      let realmWrite = buildBoxelFactoryTool('realm_write_file', config);
 
-  test('rejects realm-read targeting the target realm (workspace-only tools)', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      fetch: createMockFetch(200, { data: [] }),
+      try {
+        await realmWrite.execute({
+          'realm-url': TEST_TARGET_REALM,
+          path: 'foo.json',
+          content: '{}',
+        });
+        assert.ok(false, 'should have thrown');
+      } catch (err) {
+        assert.true(err instanceof ToolSafetyError);
+      }
     });
-    let executor = new ToolExecutor(registry, config);
 
-    try {
-      await executor.execute('realm-read', {
-        'realm-url': 'https://realms.example.test/user/target/',
-        path: 'foo.json',
-      });
-      assert.ok(false, 'should have thrown');
-    } catch (err) {
-      assert.true(err instanceof ToolSafetyError);
-      assert.true(
-        (err as Error).message.includes('cannot target the target realm'),
-        `error should mention target-realm rejection, got: ${(err as Error).message}`,
-      );
-    }
-  });
+    test('rejects realm_delete_file targeting the target realm', async function (assert) {
+      let config = makeConfig();
+      let realmDelete = buildBoxelFactoryTool('realm_delete_file', config);
 
-  test('rejects realm-write targeting the target realm', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig();
-    let executor = new ToolExecutor(registry, config);
+      try {
+        await realmDelete.execute({
+          'realm-url': TEST_TARGET_REALM,
+          path: 'foo.json',
+        });
+        assert.ok(false, 'should have thrown');
+      } catch (err) {
+        assert.true(err instanceof ToolSafetyError);
+      }
+    });
 
-    try {
-      await executor.execute('realm-write', {
-        'realm-url': 'https://realms.example.test/user/target/',
-        path: 'foo.json',
-        content: '{}',
+    test('allows realm_read_file targeting a scratch realm prefix', async function (assert) {
+      let config = makeConfig({
+        allowedRealmPrefixes: ['https://realms.example.test/user/scratch-'],
+        fetch: createMockFetch(200, { data: { id: 'foo', type: 'card' } }),
       });
-      assert.ok(false, 'should have thrown');
-    } catch (err) {
-      assert.true(err instanceof ToolSafetyError);
-    }
-  });
+      let realmRead = buildBoxelFactoryTool('realm_read_file', config);
 
-  test('rejects realm-delete targeting the target realm', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig();
-    let executor = new ToolExecutor(registry, config);
-
-    try {
-      await executor.execute('realm-delete', {
-        'realm-url': 'https://realms.example.test/user/target/',
+      let output = await realmRead.execute({
+        'realm-url': 'https://realms.example.test/user/scratch-123/',
         path: 'foo.json',
       });
-      assert.ok(false, 'should have thrown');
-    } catch (err) {
-      assert.true(err instanceof ToolSafetyError);
-    }
-  });
-
-  test('allows realm-read targeting a scratch realm prefix', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      allowedRealmPrefixes: ['https://realms.example.test/user/scratch-'],
-      fetch: createMockFetch(200, { ok: true }),
+      // boxel-cli's realm_read_file returns the parsed JSON document on success.
+      assert.deepEqual(output, { data: { id: 'foo', type: 'card' } });
     });
-    let executor = new ToolExecutor(registry, config);
 
-    let result = await executor.execute('realm-read', {
-      'realm-url': 'https://realms.example.test/user/scratch-123/',
-      path: 'foo.json',
-    });
-
-    assert.strictEqual(result.exitCode, 0);
-  });
-
-  test('rejects realm-api tool targeting unknown realm', async function (assert) {
-    let registry = new ToolRegistry();
-    let executor = new ToolExecutor(
-      registry,
-      makeConfig({
+    test('rejects realm_search targeting unknown realm', async function (assert) {
+      let config = makeConfig({
         sourceRealmUrl: 'https://realms.example.test/user/source/',
-      }),
-    );
-
-    try {
-      await executor.execute('realm-search', {
-        'realm-url': 'https://realms.example.test/other/unrelated/',
-        query: '{}',
       });
-      assert.ok(false, 'should have thrown');
-    } catch (err) {
-      assert.true(err instanceof ToolSafetyError);
-      assert.true((err as Error).message.includes('not in the allowed list'));
-    }
-  });
-
-  test('allows realm-api tool targeting scratch realm via prefix', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      sourceRealmUrl: 'https://realms.example.test/user/source/',
-      allowedRealmPrefixes: ['https://realms.example.test/user/scratch-'],
-      fetch: createMockFetch(200, { ok: true }),
-    });
-    let executor = new ToolExecutor(registry, config);
+      let realmSearch = buildBoxelFactoryTool('realm_search', config);
 
-    let result = await executor.execute('realm-search', {
-      'realm-url': 'https://realms.example.test/user/scratch-123/',
-      query: '{}',
+      try {
+        await realmSearch.execute({
+          'realm-url': 'https://realms.example.test/other/unrelated/',
+          query: '{}',
+        });
+        assert.ok(false, 'should have thrown');
+      } catch (err) {
+        assert.true(err instanceof ToolSafetyError);
+        assert.true((err as Error).message.includes('not in the allowed list'));
+      }
     });
 
-    assert.strictEqual(result.exitCode, 0);
-  });
-
-  test('rejects unknown realm even without sourceRealmUrl configured', async function (assert) {
-    let registry = new ToolRegistry();
-    let executor = new ToolExecutor(
-      registry,
-      makeConfig({
-        // No sourceRealmUrl — safety should still enforce allowed-realm targeting
-      }),
-    );
-
-    try {
-      await executor.execute('realm-search', {
-        'realm-url': 'https://evil.example.test/hacker/realm/',
-        query: '{}',
+    test('allows realm_search targeting scratch realm via prefix', async function (assert) {
+      let config = makeConfig({
+        allowedRealmPrefixes: ['https://realms.example.test/user/scratch-'],
+        fetch: createMockFetch(200, { data: [] }),
       });
-      assert.ok(false, 'should have thrown');
-    } catch (err) {
-      assert.true(err instanceof ToolSafetyError);
-      assert.true((err as Error).message.includes('not in the allowed list'));
-    }
-  });
-
-  test('rejects script tool targeting unknown realm URL', async function (assert) {
-    let registry = new ToolRegistry();
-    let executor = new ToolExecutor(registry, makeConfig());
+      let realmSearch = buildBoxelFactoryTool('realm_search', config);
 
-    try {
-      await executor.execute('search-realm', {
-        realm: 'https://evil.example.test/hacker/realm/',
+      let output = await realmSearch.execute({
+        'realm-url': 'https://realms.example.test/user/scratch-123/',
+        query: '{}',
       });
-      assert.ok(false, 'should have thrown');
-    } catch (err) {
-      assert.true(err instanceof ToolSafetyError);
-      assert.true((err as Error).message.includes('not in the allowed list'));
-    }
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Realm API execution
-// ---------------------------------------------------------------------------
-
-module('factory-tool-executor > realm-api execution', function () {
-  test('realm-search makes QUERY request', async function (assert) {
-    let capturedMethod: string | undefined;
-    let capturedUrl: string | undefined;
-
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      fetch: (async (input: RequestInfo | URL, init?: RequestInit) => {
-        capturedUrl = String(input);
-        capturedMethod = init?.method;
-        return new Response(JSON.stringify({ data: [] }), {
-          status: 200,
-          headers: { 'Content-Type': SupportedMimeType.JSON },
-        });
-      }) as typeof globalThis.fetch,
-    });
-    let executor = new ToolExecutor(registry, config);
-
-    let result = await executor.execute('realm-search', {
-      'realm-url': 'https://realms.example.test/user/target/',
-      query: JSON.stringify({ filter: { type: { name: 'Issue' } } }),
+      assert.deepEqual(output, { data: [] });
     });
 
-    assert.strictEqual(capturedMethod, 'QUERY');
-    assert.true(capturedUrl!.endsWith('_search'));
-    assert.strictEqual(result.exitCode, 0);
-  });
-
-  test('non-ok response produces exitCode 1', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      fetch: createMockFetch(404, { error: 'Not found' }),
-    });
-    let executor = new ToolExecutor(registry, config);
+    test('rejects unknown realm even without sourceRealmUrl configured', async function (assert) {
+      let config = makeConfig();
+      let realmSearch = buildBoxelFactoryTool('realm_search', config);
 
-    let result = await executor.execute('realm-search', {
-      'realm-url': 'https://realms.example.test/user/target/',
-      query: JSON.stringify({ filter: { type: { name: 'Issue' } } }),
+      try {
+        await realmSearch.execute({
+          'realm-url': 'https://evil.example.test/hacker/realm/',
+          query: '{}',
+        });
+        assert.ok(false, 'should have thrown');
+      } catch (err) {
+        assert.true(err instanceof ToolSafetyError);
+        assert.true((err as Error).message.includes('not in the allowed list'));
+      }
     });
-
-    assert.strictEqual(result.exitCode, 1);
-    let error = (result.output as Record<string, unknown>).error as string;
-    assert.true(error.startsWith('HTTP 404'));
-  });
-});
+  },
+);
 
 // ---------------------------------------------------------------------------
-// Logging
+// Standalone enforceRealmSafety — the same function adaptBoxelTool wraps with.
 // ---------------------------------------------------------------------------
 
-module('factory-tool-executor > logging', function () {
-  test('logs successful tool execution', async function (assert) {
-    let logEntries: ToolExecutionLogEntry[] = [];
-
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      fetch: createMockFetch(200, { data: [] }),
-      log: (entry) => logEntries.push(entry),
-    });
-    let executor = new ToolExecutor(registry, config);
-
-    await executor.execute('realm-search', {
-      'realm-url': 'https://realms.example.test/user/target/',
-      query: '{}',
-    });
-
-    assert.strictEqual(logEntries.length, 1);
-    assert.strictEqual(logEntries[0].tool, 'realm-search');
-    assert.strictEqual(logEntries[0].category, 'realm-api');
-    assert.strictEqual(logEntries[0].exitCode, 0);
-    assert.strictEqual(typeof logEntries[0].durationMs, 'number');
-    assert.strictEqual(logEntries[0].error, undefined);
-  });
-
-  test('logs failed tool execution', async function (assert) {
-    let logEntries: ToolExecutionLogEntry[] = [];
-
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      fetch: createMockFetch(500, { error: 'Internal error' }),
-      log: (entry) => logEntries.push(entry),
-    });
-    let executor = new ToolExecutor(registry, config);
-
-    let result = await executor.execute('realm-search', {
-      'realm-url': 'https://realms.example.test/user/target/',
-      query: '{}',
-    });
-
-    assert.strictEqual(result.exitCode, 1);
-    assert.strictEqual(logEntries.length, 1);
-    assert.strictEqual(logEntries[0].exitCode, 1);
+module('factory-tool-executor > enforceRealmSafety', function () {
+  test('passes when realm-url matches target and tool is not bypass-restricted', function (assert) {
+    let safety: RealmSafetyConfig = { targetRealmUrl: TEST_TARGET_REALM };
+    enforceRealmSafety(
+      'realm_search',
+      { 'realm-url': TEST_TARGET_REALM, query: '{}' },
+      safety,
+    );
+    assert.ok(true, 'no throw');
   });
-});
-
-// ---------------------------------------------------------------------------
-// ToolResult serialization
-// ---------------------------------------------------------------------------
 
-module('factory-tool-executor > ToolResult shape', function () {
-  test('successful result has expected shape', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      fetch: createMockFetch(200, { cards: ['a', 'b'] }),
-    });
-    let executor = new ToolExecutor(registry, config);
-
-    let result = await executor.execute('realm-search', {
-      'realm-url': 'https://realms.example.test/user/target/',
-      query: '{}',
-    });
-
-    assert.strictEqual(typeof result.tool, 'string');
-    assert.strictEqual(typeof result.exitCode, 'number');
-    assert.strictEqual(typeof result.durationMs, 'number');
-    assert.notStrictEqual(result.output, undefined, 'output is defined');
+  test('throws when bypass-restricted tool targets the target realm', function (assert) {
+    let safety: RealmSafetyConfig = { targetRealmUrl: TEST_TARGET_REALM };
+    assert.throws(
+      () =>
+        enforceRealmSafety(
+          'realm_read_file',
+          { 'realm-url': TEST_TARGET_REALM, path: 'foo.json' },
+          safety,
+        ),
+      ToolSafetyError,
+    );
   });
 
-  test('ToolResult can be serialized to JSON', async function (assert) {
-    let registry = new ToolRegistry();
-    let config = makeConfig({
-      fetch: createMockFetch(200, { data: [1, 2, 3] }),
-    });
-    let executor = new ToolExecutor(registry, config);
-
-    let result = await executor.execute('realm-search', {
-      'realm-url': 'https://realms.example.test/user/target/',
-      query: '{}',
-    });
-
-    let serialized = JSON.stringify(result);
-    let deserialized = JSON.parse(serialized) as ToolResult;
-    assert.strictEqual(deserialized.tool, 'realm-search');
-    assert.strictEqual(deserialized.exitCode, 0);
-    assert.deepEqual(deserialized.output, { data: [1, 2, 3] });
+  test('rejects sibling-host URL that string-prefix-matches an allowed prefix', function (assert) {
+    let safety: RealmSafetyConfig = {
+      targetRealmUrl: TEST_TARGET_REALM,
+      allowedRealmPrefixes: ['https://realms.example.test/'],
+    };
+    assert.throws(
+      () =>
+        enforceRealmSafety(
+          'realm_search',
+          {
+            'realm-url': 'https://realms.example.test.evil.com/hacker/realm/',
+            query: '{}',
+          },
+          safety,
+        ),
+      ToolSafetyError,
+      'sibling host masquerading as a path prefix should not be allowed',
+    );
   });
-});
-
-// Timeout enforcement for realm-api calls is now the client's responsibility
-// (BoxelCLIClient/ProfileManager own the fetch pipeline), so the executor no
-// longer wraps calls in an AbortController. The spawn-based timeout for
-// script and boxel-cli tools is covered elsewhere.
 
-// ---------------------------------------------------------------------------
-// composeBoxelCliInvocation
-// ---------------------------------------------------------------------------
-
-module('factory-tool-executor > composeBoxelCliInvocation', function () {
-  test('prepends --quiet by default', function (assert) {
-    let args = composeBoxelCliInvocation(['sync', '.', '--prefer-local']);
-    assert.deepEqual(args, ['boxel', '--quiet', 'sync', '.', '--prefer-local']);
+  test('rejects allowed-prefix exploit where origin differs even if path string starts the same', function (assert) {
+    let safety: RealmSafetyConfig = {
+      targetRealmUrl: TEST_TARGET_REALM,
+      allowedRealmPrefixes: ['https://realms.example.test/user/scratch-'],
+    };
+    assert.throws(
+      () =>
+        enforceRealmSafety(
+          'realm_search',
+          {
+            'realm-url': 'https://evil.example.com/user/scratch-123/',
+            query: '{}',
+          },
+          safety,
+        ),
+      ToolSafetyError,
+    );
   });
 
-  test('omits --quiet when debug is true', function (assert) {
-    let args = composeBoxelCliInvocation(['sync', '.', '--prefer-local'], {
-      debug: true,
-    });
-    assert.deepEqual(args, ['boxel', 'sync', '.', '--prefer-local']);
+  test('allows within-origin path prefix matching', function (assert) {
+    let safety: RealmSafetyConfig = {
+      targetRealmUrl: TEST_TARGET_REALM,
+      allowedRealmPrefixes: ['https://realms.example.test/user/scratch-'],
+    };
+    enforceRealmSafety(
+      'realm_search',
+      {
+        'realm-url': 'https://realms.example.test/user/scratch-123/',
+        query: '{}',
+      },
+      safety,
+    );
+    assert.ok(true, 'no throw');
   });
 
-  test('treats debug:false the same as omitted', function (assert) {
-    let args = composeBoxelCliInvocation(['status', '.'], { debug: false });
-    assert.deepEqual(args, ['boxel', '--quiet', 'status', '.']);
+  test('throws when realm-url matches the configured source realm', function (assert) {
+    let safety: RealmSafetyConfig = {
+      targetRealmUrl: TEST_TARGET_REALM,
+      sourceRealmUrl: 'https://realms.example.test/user/source/',
+    };
+    assert.throws(
+      () =>
+        enforceRealmSafety(
+          'realm_search',
+          {
+            'realm-url': 'https://realms.example.test/user/source/',
+            query: '{}',
+          },
+          safety,
+        ),
+      ToolSafetyError,
+    );
   });
 });
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function createMockFetch(
-  status: number,
-  body: unknown,
-): typeof globalThis.fetch {
-  return (async () => {
-    return new Response(JSON.stringify(body), {
-      status,
-      headers: { 'Content-Type': SupportedMimeType.JSON },
-    });
-  }) as typeof globalThis.fetch;
-}
diff --git a/packages/software-factory/tests/factory-tool-registry.test.ts b/packages/software-factory/tests/factory-tool-registry.test.ts
index 09aa6d57001..cfa03fe344f 100644
--- a/packages/software-factory/tests/factory-tool-registry.test.ts
+++ b/packages/software-factory/tests/factory-tool-registry.test.ts
@@ -1,9 +1,7 @@
 import { module, test } from 'qunit';
 
 import {
-  BOXEL_CLI_TOOLS,
   getDefaultToolRegistry,
-  REALM_API_TOOLS,
   SCRIPT_TOOLS,
   ToolRegistry,
   type ToolManifest,
@@ -14,14 +12,16 @@ import {
 // ---------------------------------------------------------------------------
 
 module('factory-tool-registry > ToolRegistry construction', function () {
-  test('default registry includes all built-in tools', function (assert) {
+  test('default registry includes only script tools (realm-api tools live in boxel-cli getToolDefinitions, not the registry)', function (assert) {
     let registry = new ToolRegistry();
-    let expectedCount =
-      SCRIPT_TOOLS.length + BOXEL_CLI_TOOLS.length + REALM_API_TOOLS.length;
     assert.strictEqual(
       registry.size,
-      expectedCount,
-      `registry has ${expectedCount} tools`,
+      SCRIPT_TOOLS.length,
+      `default registry has ${SCRIPT_TOOLS.length} tools`,
+    );
+    assert.false(
+      registry.has('realm_read_file'),
+      'realm-* tools are not registered',
     );
   });
 
@@ -118,8 +118,7 @@ module('factory-tool-registry > has', function () {
   test('returns true for registered tool', function (assert) {
     let registry = new ToolRegistry();
     assert.true(registry.has('search-realm'));
-    assert.true(registry.has('boxel-sync'));
-    assert.true(registry.has('realm-search'));
+    assert.true(registry.has('run-realm-tests'));
   });
 
   test('returns false for unregistered tool', function (assert) {
@@ -156,12 +155,12 @@ module('factory-tool-registry > validateArgs', function () {
     assert.true(errors[0].includes('Unknown tool'));
   });
 
-  test('multiple missing required args produce multiple errors', function (assert) {
+  test('returns error for unknown tool with empty args', function (assert) {
     let registry = new ToolRegistry();
-    let errors = registry.validateArgs('realm-write', {});
+    let errors = registry.validateArgs('not-a-tool', {});
     assert.true(
-      errors.length >= 3,
-      `expected at least 3 errors, got ${errors.length}`,
+      errors.length >= 1,
+      `expected at least 1 error, got ${errors.length}`,
     );
   });
 
@@ -201,26 +200,6 @@ module('factory-tool-registry > built-in manifests', function () {
     }
   });
 
-  test('all boxel-cli tools have correct category', function (assert) {
-    for (let tool of BOXEL_CLI_TOOLS) {
-      assert.strictEqual(
-        tool.category,
-        'boxel-cli',
-        `${tool.name} has category "boxel-cli"`,
-      );
-    }
-  });
-
-  test('all realm-api tools have correct category', function (assert) {
-    for (let tool of REALM_API_TOOLS) {
-      assert.strictEqual(
-        tool.category,
-        'realm-api',
-        `${tool.name} has category "realm-api"`,
-      );
-    }
-  });
-
   test('all tools have unique names', function (assert) {
     let registry = new ToolRegistry();
     let manifests = registry.getManifests();
@@ -267,26 +246,13 @@ module('factory-tool-registry > built-in manifests', function () {
     assert.true(registry.has('run-realm-tests'));
   });
 
-  test('expected boxel-cli tools are registered', function (assert) {
-    let registry = new ToolRegistry();
-    assert.true(registry.has('boxel-sync'));
-    assert.true(registry.has('boxel-push'));
-    assert.true(registry.has('boxel-pull'));
-    assert.true(registry.has('boxel-status'));
-    assert.true(registry.has('boxel-create'));
-    assert.true(registry.has('boxel-history'));
-  });
-
-  test('expected realm-api tools are registered', function (assert) {
+  test('realm-api tools are NOT in the registry (they live in boxel-cli getToolDefinitions)', function (assert) {
     let registry = new ToolRegistry();
-    // realm-read/realm-write/realm-delete are scoped to non-target realms
-    // by the executor's safety check; target-realm I/O goes through the
-    // workspace.
-    assert.true(registry.has('realm-read'));
-    assert.true(registry.has('realm-write'));
-    assert.true(registry.has('realm-delete'));
-    assert.true(registry.has('realm-search'));
-    assert.true(registry.has('realm-create'));
+    assert.false(registry.has('realm_read_file'));
+    assert.false(registry.has('realm_write_file'));
+    assert.false(registry.has('realm_delete_file'));
+    assert.false(registry.has('realm_search'));
+    assert.false(registry.has('create_realm'));
   });
 });