> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithtrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Version History & Rollback

> How Trace tracks every AI edit with local and cloud version history, per-message undo, and a restore dialog.

## Overview

Every time the AI modifies your schematic or PCB, Trace automatically creates a version snapshot. You never lose work — you can roll back to any previous state at any time. Version history works through three complementary systems.

## Local History

Local history is the primary versioning system. It works offline and requires no account or network connection.

### How It Works

* Trace maintains a `.history/` directory inside your project folder
* Each version is a git commit containing the full file content at that point in time
* Versions are created automatically in the background after every AI edit
* The git-based system supports atomic commits, so partial saves can't corrupt your history

### Background Saves

Version saves happen in the background without interrupting your workflow. After the AI completes an edit, Trace:

1. Captures the current state of modified files
2. Commits them to the local `.history/` repository
3. Records a summary of what changed

If a background save fails (e.g., disk full), it logs a warning but doesn't block your work. The next successful save will capture the current state.

## Cloud Sync

Cloud versions are stored in Trace's backend and sync across devices.

### When Cloud Versions Are Created

Cloud versions are saved at the same time as local versions — after each AI edit. They contain the full file content (not diffs), so any version can be restored independently.

### Cross-Device Access

If you sign in to Trace on a different machine, your cloud-synced versions are available for restore. This is useful for:

* Moving between a desktop and laptop
* Recovering after a machine failure
* Sharing a specific version state with a collaborator

<Note>
  Cloud sync requires an internet connection and a Trace account. Local history works regardless.
</Note>

## Per-Message Undo

Every assistant message in the chat is tagged with a `version_id` that represents the state of your design **after** that message's edits were applied.

### How to Undo

Click the **undo button** on any assistant message in the chat to restore your design to the state before that message's edits. The rollback is:

* **Non-destructive** — Rolling back creates a new version rather than deleting history, so you can always go forward again
* **Instant** — The restore loads from local history first (fast), with cloud as fallback
* **Scoped** — Only the files that were modified by the AI are affected

### Version ID Semantics

To understand rollback correctly:

* The `version_id` on message N represents the state **after** message N's edits
* To restore to the state **before** message N, Trace uses the `version_id` from message N-1
* If message N-1 has no `version_id` (it was a question, not an edit), Trace walks further back to find the last edit

## Restore Dialog

For browsing and restoring from the full version history (not just per-message), Trace provides a dedicated restore dialog.

### What the Dialog Shows

| Column            | Description                                |
| ----------------- | ------------------------------------------ |
| **Timestamp**     | When the version was created               |
| **Summary**       | A brief description of what the AI changed |
| **Hash**          | The git commit hash for the local version  |
| **Changed Files** | Which files were modified in this version  |

### How to Access

Open the restore dialog from the chat panel's version history menu. Select any version and click **Restore** to roll back to that state.

## AI Edit Undo/Redo

Beyond per-message rollback, Trace maintains a full undo/redo stack for AI edits through the `AI_COMMIT` system:

* Each AI edit is recorded as an atomic commit with before/after state
* **Undo** reverses the last AI edit, restoring all modified files to their previous state
* **Redo** reapplies a previously undone edit
* The undo/redo stack is per-tab, so undoing in one conversation doesn't affect another

This is separate from the manual undo (Ctrl+Z) in the schematic and PCB editors, which handles your own manual edits.

## Best Practices

1. **Use Plan mode for risky changes** — Plan mode lets you review before execution. If you don't like the result, undo rolls back everything the plan did.
2. **Check version history before major redesigns** — If you're about to have the AI redesign a section, note the current state so you can easily find it in history.
3. **Local history survives uninstalls** — The `.history/` directory is inside your project folder, not in the app. It persists even if you uninstall and reinstall Trace.
4. **Cloud sync is a backup, not a replacement** — Local history is faster and works offline. Cloud sync adds cross-device access and disaster recovery.