---
name: mesh_file_explorer
emoji: "📂"
description: High-performance mesh-wide file orchestration, synchronization, and manipulation.
skill_type: local
is_enabled: true
features:
- swarm_control
- agent_harness
config:
  internal_module: app.core.grpc.core.mirror
  actions:
  - list
  - read
  - write
  - delete
  - move
  - copy
  - stat
  parameters:
    type: object
    properties:
      action:
        type: string
        enum: [list, read, write, delete, move, copy, stat]
        description: File system action.
      path:
        type: string
        description: Relative path to the file/directory.
      to_path:
        type: string
        description: Destination path for move/copy operations.
      node_id:
        type: string
        description: "The target node ID. Use 'hub' or 'local' for local Hub filesystem actions."
      content:
        type: string
        description: Optional content for write action.
      session_id:
        type: string
        description: "Target sync session workspace (default: 'current')."
      recursive:
        type: boolean
        description: Enable recursive mode for list or delete.
    required:
    - action
    - path
is_system: true
---

# Mesh File Explorer Protocol

A high-performance file management system designed for distributed agent meshes. It operates on the **Ghost Mirror VFS**, ensuring that file changes are automatically synchronized across all attached compute nodes in real-time.

---

## Operational Intelligence

You are the **Decentralized File Management Specialist**. Select your operational mode based on the target requirements:

### Mode 1: 🔄 Synchronized Workspace (`session_id='current'`)
Default mode. Any change (write/delete/move) is instantly pushed to all nodes in the mesh. This is the **authoritative** way to edit code.

> [!IMPORTANT]
> **HUB WRITE SAFETY**
> When targeting the Hub (`node_id='hub'`), you **MUST** use `mesh_file_explorer` for all `write`, `delete`, and `move` actions. 
> - **WHY**: This skill triggers the gRPC synchronization engine. Native shell commands (via terminal) bypass this engine, leading to "ghost" files and mesh drift.

### Mode 2: 🖥️ Physical Node Maintenance
Use this mode to interact with system files or directories OUTSIDE the synchronized workspace.
- **Trigger**: Set `session_id` to `__fs_explorer__`.
- **Pathing**: Use **ABSOLUTE** paths (e.g., `/etc/hosts`).

---

## Actions Protocol

### Core Operations
*   **`list`**: Efficiently explore directory structures. 
*   **`read`**: Retrieve contents for analysis. 
*   **`write`**: Create/Update files with automatic mesh-wide propagation.
*   **`delete`**: Remove files with guaranteed deletion broadcast across the mesh.

### Advanced Operations (M6+)
*   **`move`**: Renames or reposition a file/directory. This is **atomic** and significantly faster than a read-write-delete sequence during refactors.
*   **`copy`**: Duplicates files or entire trees within the decentralized mirror without AI-side data transit.
*   **`stat`**: Fetches metadata (size, mod-time, link status). Use this for high-speed existence checks to save context and latency.

---

## Action Intelligence Patterns

### Pattern: The Atomic Refactor
When renaming a project structure, use `move` instead of `read` + `write`. It ensures that large directory trees are repositioned instantly and maintains mesh consistency.

### Pattern: Fast Context Recovery
Before reading a large file to check its existence, use `stat`. This allows you to verify the environment state in milliseconds without consuming tokens for the file body.

### Pattern: The Physical-to-Mesh Bridge (Importing)
To "import" a file from a node's physical disk (outside the sandbox) into the Web UI Explorer:
1. Identify the source absolute path (e.g., `/mnt/data/photo.jpg`).
2. Use `mesh_terminal_control` to copy it into the sync workspace: `cp "/mnt/data/photo.jpg" "/tmp/cortex-sync/{{session_id}}/photo.jpg"`.
3. The File Explorer UI will automatically detect and sync this new file.

> [!CAUTION]
> Avoid performing massive recursive `list` operations on huge node-local paths (like `/usr/lib/` or `/node_modules/`) unless absolutely necessary, as it can saturate the gRPC control stream.
