File Protection and Version Management

This Skill uses MiniVCS to track all file operations with version history.

Runtime requirement: Python 3 is required to run scripts/minivcs/minivcs.py.

Script location: scripts/minivcs/minivcs.py in the same directory as this SKILL.md
(Before executing, first determine the directory containing this file. It is referred to as $SKILL_DIR below.)

Core mechanism:

• - Modify: Saves an incremental diff plus a full snapshot from before the modification, supporting rollback
• Delete: Moves the full file into ~/.openclaw/minivcs/trash/, supporting restore
• All files are indexed, with different retention periods based on importance
• After every operation, the full record table is scanned automatically to find expired records and ask the user for confirmation

Usage limitations:

• - Binary files (images, PDFs, audio/video, etc.): Text diffs cannot be generated. For binary-file protection, MiniVCS stores a full local .bak copy instead. This applies to binary-file backup/rollback protection, and deletion protection also stores a full local copy in ~/.openclaw/minivcs/trash/. The user must be informed before the operation because storage usage may be relatively high.
• The first record cannot be rolled back: When a file is recorded for the first time, there is not yet any historical baseline, so that record has no snapshot. After that, each call to record_modify following an edit automatically saves a snapshot, allowing rollback to the state before any edit.
• Local storage notice: Protection data is stored locally under ~/.openclaw/minivcs/. This Skill does not provide encryption or remote sync.

---

Prerequisite Check: Confirm Python Is Installed

Before performing any operation, you must first check whether Python 3 is installed in the user's environment. This Skill requires Python 3 and should not run without it.

How to check

CODEBLOCK0

• - If the output is Python 3.x.x, it is installed and you can continue
• If it says command not found or is not recognized as an internal or external command, stop and tell the user that this Skill requires Python 3

Dependency boundary

If Python 3 is missing:

• - Do not run dependency installation commands from this Skill
• Do not run remote install scripts such as INLINECODE12
• Do not write to shell config files such as ~/.zshrc or INLINECODE14
• Do not modify global environment variables on the user's behalf from this Skill
• Tell the user that Python 3 is required, and ask them to install it first or explicitly authorize a separate environment-setup flow

Note: On some Windows systems the command is python, while on macOS/Linux it is python3.
In all commands below that use python, replace it with the correct command for the actual environment.

---

Retention Policy

File Type	Retention Days	Decision Rule
Important files	14 days	System paths (/etc/, /root/, /usr/local/etc/, /opt/), user config directories (~/.ssh/, ~/.gnupg/, ~/.config/, ~/.openclaw/, ~/.kube/, ~/.docker/, ~/.aws/, ~/.azure/, ~/.local/share/), Windows system directories (C:\Windows\, C:\ProgramData\, C:\Program Files\), config files (.yaml/.toml/.env, etc.), entry files (main.py/index.ts, etc.)
Normal files

7 days | All other files |

When each record is created, the expireAt (expiration timestamp) and expireAtDatetime (human-readable time) fields are set automatically.

---

Excluded Paths (Auto-Skip)

Files whose path contains any of the following segments are automatically skipped by record_modify and record_delete. These are generated, vendored, or cache directories that should not be version-tracked:

INLINECODE40, .git, __pycache__, .venv, venv, .tox, .mypy_cache, .pytest_cache, .ruff_cache, dist, build, .next, .nuxt, INLINECODE53

When a file is skipped, the return value will contain "skipped": true and a "reason" field. The Agent should inform the user that the file was not tracked and explain why.

---

Binary File Size Warning

When a binary file exceeds 50 MB, the return value from record_modify (binary backup) will include:

• - INLINECODE57
• INLINECODE58: a human-readable description of the file size and threshold

When sizeWarning is present, the Agent must explicitly inform the user of the file size and ask for confirmation before proceeding with any further binary backup operations on similarly large files.

---

Operation Flow

Step 1: Initialize the MiniVCS Working Directory

On first use, the storage directory is created automatically. No extra action is required:

CODEBLOCK1

All data is stored uniformly in ~/.openclaw/minivcs/:

~/.openclaw/minivcs/
  logs.json     # operation log (includes the expireAt field)
  diffs/        # incremental patches for text file modifications
  bases/        # baseline for the next comparison (named by full relative path, so no same-name conflicts)
  snapshots/    # full snapshots before text file modifications (used for rollback)
  trash/        # full backups of deleted files (used for restore)
  backups/      # full `.bak` copies of binary files (used for rollback)

---

Step 2: Ask the User for Confirmation Before the Operation

Before deleting or modifying a file, you must explain the following to the user and wait for confirmation:

1. 1. The file path to be operated on
2. The operation type (modify / delete)
3. The purpose and intent of the operation
4. The possible impact
5. Explain the local storage behavior: this Skill stores protection data under ~/.openclaw/minivcs/
6. For text-file modifications, explain that MiniVCS stores diffs and snapshots so the file can be rolled back
7. For deletions, explain that MiniVCS stores a full local copy in ~/.openclaw/minivcs/trash/ so the file can be restored
8. If the file is binary, explicitly explain that protection uses a full local copy rather than a text diff, and ask whether the user wants that local copy to be stored before deletion or binary-file protection
9. If a binary backup returns sizeWarning: true, the Agent must display the file size and warning message to the user, and ask for explicit confirmation before proceeding

If the file is binary and the user does not want a local stored copy, do not treat the operation as a protected delete/rollback flow under this Skill.

If the path is auto-skipped (return contains "skipped": true), inform the user that the file was not tracked and state the reason.

Example before the operation:
CODEBLOCK3

Example for a binary file before deletion:
CODEBLOCK4

After the operation completes, you must inform the user of the record result, for example:

# After a modification is completed
The modification to path/to/file.py has been completed, and this change has been recorded (Record ID: 1710000000000).
- Change summary: +5 lines, -2 lines
- Retention period: 7 days (expires at: 2026-03-20 10:00:00)
- Rollback available: yes (use restore 1710000000000 to recover the state before the modification)
If you want to view the diff or roll it back, let me know.

# After a deletion is completed
path/to/file.py has been moved to the trash and backed up (Record ID: 1710000001000).
- Retention period: 14 days (expires at: 2026-03-27 10:00:00) [important file]
If you want to restore this file, let me know.

---

Step 3: Operate on Files with MiniVCS

Modify a file (supports rollback)

Just call record once after each edit. The snapshot chain is formed automatically and supports rolling back to any historical state:

CODEBLOCK6

CODEBLOCK7

Python API:
CODEBLOCK8

Delete a file (supports restore)

Do not delete the file directly. Use record_delete instead, and the file is moved into trash automatically.

Before running record_delete:

• - Tell the user that a full local copy will be stored in INLINECODE69
• If the file is binary, explicitly ask whether they want that local copy to be stored
• Only proceed with protected deletion after the user confirms the local storage behavior

CODEBLOCK9

Python API:
CODEBLOCK10

Restore / Roll back

The same restore command handles both scenarios:

CODEBLOCK11

Python API:

result = vcs.restore_file(record_id="...")
# After DELETE succeeds: the record is marked as RESTORED and no longer appears in the trash list
# After MODIFY succeeds: the record is marked as ROLLED_BACK
# Repeated restore: returns {"success": False, "error": "already been restored/rolled_back"}

---

Step 4: Handle Expired Cleanup Notifications (must be done after every operation)

After each call to record_modify or record_delete, the return value contains the due_for_cleanup field.

If due_for_cleanup is not empty, the Agent must:

1. 1. Show the user the list of expired records (sorted from earliest to latest)
2. Ask which ones can be deleted and which ones need an extension

Example display format:
CODEBLOCK13

Handling after the user responds:

CODEBLOCK14

Command line:

# View all expired records
python "$SKILL_DIR/scripts/minivcs/minivcs.py" cleanup --project-root <project_root>

# Confirm cleanup
python "$SKILL_DIR/scripts/minivcs/minivcs.py" cleanup --confirm --project-root <project_root>

# Extend one record
python "$SKILL_DIR/scripts/minivcs/minivcs.py" extend <record_id> --project-root <project_root>

---

Other Common Operations

CODEBLOCK16

---

Record Field Reference

Field	Type	Description
INLINECODE75	string	Unique record ID (millisecond timestamp)
INLINECODE76

string | Relative or absolute path |
| action | string | MODIFY / DELETE / BINARY_BACKUP / RESTORED / ROLLED_BACK |
| timestamp | number | Creation time (milliseconds) |
| datetime | string | Creation time (human-readable) |
| isImportant | bool | Whether the file is important |
| retentionDays | number | Retention days (7 or 14) |
| expireAt | number | Expiration time (milliseconds) |
| expireAtDatetime | string | Expiration time (human-readable) |
| diffFile | string | Diff patch path (MODIFY only) |
| snapshotFile | string | Pre-modification snapshot path (only present when MODIFY has a snapshot) |
| trashFile | string | Trash backup path (DELETE only) |
| backupFile | string | .bak copy path (BINARY_BACKUP only) |
| summary | string | Change summary |

---

Full Operation Flow Diagram

CODEBLOCK17