Viewing Project History

The History panel is the home for everything version control. This page walks through how to open it, read the timeline, inspect what a version changed, and rename versions so the timeline reads cleanly later on.

Opening the History Panel

There are two ways to open it:

1. Click the History button at the top of any project page.
2. Press Cmd-H (Mac) or Ctrl-H (Windows / Linux) anywhere inside a project.

The History panel slides in from the right side of the screen. Click anywhere outside it (or press Esc) to close.

Reading the Timeline

The timeline lists every closed changeset for your project, newest first. Each entry is a card showing:

Empty State

If you have just created a project and haven't made any edits yet, the panel shows: "No history yet. Start editing to see changesets appear here." Run a generation or make a manual edit, and the first changeset appears within a few seconds.

Loading More History

The panel loads versions in batches of around 20 to stay fast. If you have more history, a Load more button appears at the bottom — click it to fetch the next page of changesets. The timeline scrolls infinitely as you load.

Inspecting What a Version Changed

Click the View button on any changeset to open the diff modal. This shows the exact set of operations recorded in that version, grouped by entity type.

For each operation you see:

• Symbol:
  • + (green) — a new entity was created
  • ~ (amber) — an existing entity was updated
  • − (red) — an entity was deleted
• Summary — the entity's name, title, or "I want to…" line, so you can recognise what was touched at a glance.

Operations are grouped by entity type (Features, User Stories, Schema Columns, etc.) with a count next to each group heading — e.g. "User stories (12)".

A typical diff modal might show

Features (3)
  + User onboarding flow
  ~ Dashboard analytics
  − Legacy CSV import

User stories (8)
  + As a user, I want to reset my password
  + As a user, I want to set up two-factor auth
  ~ As an admin, I want to invite team members
  ...

Schema columns (2)
  + email_verified_at
  ~ users.password_hash

This makes it easy to answer "what did the AI do in that last regeneration?" or "did my last edit accidentally delete something I wanted to keep?"

If the diff has more entity types than fit on screen, scroll inside the modal.

Per-row Field-level Diffs

For now the modal shows the high-level "what was touched". A future iteration will add field-level before/after diffs (e.g. showing that priority changed from medium to high on a specific feature). The data is already captured — the UI to drill in is on the roadmap.

Renaming a Changeset

Auto-generated titles are functional but generic — things like "Direct edits" or "AI generation: features". To make the timeline easier to scan later, you can rename any changeset to something meaningful.

1. Hover over the title — a pencil icon appears next to it.
2. Click the title.
3. An input box replaces the title. Type your new label.
4. Confirm with the check icon, or cancel with the X icon (your typed text is discarded).

Good titles answer the question "what was I trying to accomplish here?":

• "Added compliance officer persona + 3 features"
• "Renamed Notifications to Alerts everywhere"
• "First pass on schema for billing tables"
• "Cleanup: removed legacy MVP features"

Rename liberally — there is no cost and it makes the timeline far more useful when you come back days or weeks later.

What If There's No Snapshot?

For very old versions or versions that were never closed (rare edge case), the timeline may show "No snapshot — read only" instead of a Revert button. You can still click View to inspect what the change did, but you can no longer roll back directly to that exact point. You can still roll back to any later version that does have a snapshot.

In practice, recent versions (the ones you actually care about reverting to) will always have snapshots available.

How Long Does History Go Back?

VibeMap keeps the full timeline of changesets indefinitely so you can always see what happened. Snapshots — the underlying data needed to revert — are kept on a longer rolling window. Project owners on paid plans get longer retention than free-tier projects.

If you need to retain a specific historical state forever, the safest pattern today is to revert into a fresh changeset at the point you care about — that version becomes the "current" state and will be snapshotted as part of normal operation.

Tips for an Organised Timeline

• Rename agent-generated changesets — the conversational agent often creates changesets with neutral titles like "MCP tool call". Renaming these to "Added auth feature" makes a huge difference later.
• Take a checkpoint before risky operations — if you are about to ask the AI to do something experimental ("rewrite all my schema"), open History first, note the current vN, and rename the most recent closed changeset to something like "Stable: pre-schema-rewrite". You will know exactly where to roll back if the experiment goes sideways.
• Use the actor badges to scan for AI vs your edits — if you are looking for "what changed last Tuesday afternoon", the colour-coded badges make it easy to spot whose changes those were without reading every title.

Next Steps

• Reverting changes — how to roll back to any version and what happens to your current state.
• Conversational agent — the most common source of changesets in a typical project.