Workspaces

A workspace is a named container that sets a root directory and scopes the projects inside it. Each workspace is stored on disk as a small JSON file, so it can be moved, shared, or checked into version control alongside the site it describes.

What a workspace is

A workspace ties a name to a root directory. Every project created while the workspace is open is scoped to that root, keeping crawl data, exports, and configuration in one predictable location.

On disk a workspace is a .consuela-workspace JSON file with four fields:

Field	Description
`version`	Schema version of the workspace file.
`name`	Display name shown in the picker and title bar.
`rootPath`	Absolute path to the directory that scopes this workspace's projects.
`createdAt`	ISO 8601 timestamp recorded when the workspace was first saved.

The file is the source of truth for the root path. If you move the workspace directory, update rootPath in the file so the app can locate projects on the next open.

Creating and saving

Select New Workspace in the workspace picker. This creates an unsaved workspace immediately — no file dialog appears yet, so you can start working before deciding where the file belongs on disk.

The first time you save, a file dialog prompts you to choose a location. The workspace name and root path are derived from the directory you select, and the .consuela-workspace file is written there. Subsequent saves overwrite the same file silently with no further prompts.

Opening an existing workspace uses a file picker filtered to .consuela-workspace files. If the selected file matches one already in the recent list, the existing entry is reused rather than creating a duplicate.

Workspace picker

The workspace picker is the first dialog you see when the app opens. It provides two actions at the top — New Workspace and Open Workspace File — followed by a list of recently used workspaces.

Each entry in the recent list shows the workspace name, the path to its file, and a relative date indicating when it was last opened. A remove button on each row takes the workspace out of the list without deleting the file from disk.

At the bottom of the dialog, a Continue without workspace link skips the picker entirely. Projects created in this mode are not scoped to any root directory.

The recent workspace list is stored in localStorage. It persists across sessions but does not sync between machines or browsers. The .consuela-workspace file on disk remains the authoritative record of the workspace's root path — the local list is a convenience for quick access.