# Workspace model (/docs/concepts/workspace-model)



Bowline builds continuity from a few precise ideas. Once you know them, the rest
of the product (sync, conflicts, work views, and agent leases) reads as
variations on the same model. This page defines those ideas and how project state
moves forward.

## The core terms [#the-core-terms]

Bowline tracks project state as durable Workspace Snapshots, a single current
Workspace Head per project, and overlays that hold in-progress writes until
they're safe to merge.

| Term               | What it is                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Workspace Snapshot | A durable project state that follows authorized machines and agents, including uncommitted, source-like work.                   |
| Workspace Head     | The current canonical Workspace Snapshot for a project.                                                                         |
| Machine Overlay    | Local writes from one machine before they advance the Workspace Head.                                                           |
| Agent Overlay      | Isolated writes from an [agent lease](/docs/concepts/agent-leases) before they advance the Workspace Head or become a conflict. |
| Resolution Overlay | A proposed [conflict](/docs/concepts/conflicts) repair output, before you accept it.                                            |
| Automatic Merge    | A proven-safe merge that advances the Workspace Head without any action from you.                                               |
| File Identity      | The continuity of a file across path changes, so safe edits can follow a rename.                                                |

A project has exactly one current Workspace Head, and it points to one Workspace
Snapshot. Everything else is how Bowline creates a new Workspace Snapshot and
moves the Workspace Head to it.

## How state advances [#how-state-advances]

Most of the time, state advances without you noticing. As you work, your writes
collect in a Machine Overlay based on the current Workspace Snapshot. When those
writes don't clash with newer work, Bowline turns them into a new Workspace
Snapshot and advances the Workspace Head automatically.

The same is true for agents. An Agent Overlay holds a lease's writes; if they
don't conflict, they become a Workspace Snapshot and advance the Workspace Head,
with no Git publish required. Publishing to a remote stays your decision and your
tool's job.

1. You (or an agent) write files. The writes land in an overlay based on the
   current head.
2. Bowline coalesces noisy file events and checks the writes against the latest
   Workspace Head.
3. If the changes are safe, an Automatic Merge advances the Workspace Head to a
   new Workspace Snapshot.
4. If they aren't safe, Bowline opens a [Sync Conflict](/docs/concepts/conflicts)
   and preserves both sides.

<Callout type="info">
  Only a Resolution Overlay needs your acceptance. Ordinary, non-conflicting
  machine and agent overlays advance the Workspace Head on their own. That's what
  makes the workspace feel like it just stays in sync.
</Callout>

## What Automatic Merge can do safely [#what-automatic-merge-can-do-safely]

Automatic Merge is deliberately conservative. It proves a merge is safe before it
advances the Workspace Head, rather than guessing. It handles changes that are mechanically
safe to combine:

* Edits to different files.
* Edits to different regions (hunks) of the same text file.
* Safe edits carried across a rename, when File Identity has strong evidence that
  it's the same file.

For [Structured Text](/docs/concepts/conflicts), which covers config and manifest
files, Automatic Merge applies only when the merged output still parses. If a merge
would produce a file that no longer parses, Bowline treats it as a conflict
instead of risking a broken config.

## Overlays keep work isolated until it's safe [#overlays-keep-work-isolated-until-its-safe]

Overlays are how Bowline keeps in-progress writes from corrupting canonical
state. A Machine Overlay isolates one machine's pending writes. An Agent Overlay
isolates one lease's writes. A Resolution Overlay holds a proposed conflict fix
until you accept it.

This is also the basis for [work views](/docs/concepts/work-views): an explicit,
review-before-apply overlay under `~/Code/.work` that never touches the main
project until you accept it.

## Next steps [#next-steps]

* [Sync and continuity](/docs/concepts/sync-and-continuity): how writes are
  captured and synced as you work.
* [Conflicts](/docs/concepts/conflicts): what happens when work diverges.
* [Work views](/docs/concepts/work-views): isolated, review-before-apply project
  views.
* [Agent leases](/docs/concepts/agent-leases): scoped authority for coding
  agents.