KittyCAD · pierremtb · Aug 11, 2026 · Jul 28, 2026 · Aug 3, 2026 · Aug 3, 2026
@@ -1,7 +1,7 @@
 ---
 title: Aquarium
 excerpt: Share and discover public Zoo models through the Aquarium CAD Gallery.
-sidebarPosition: 4
+sidebarPosition: 6
 ---
 
 Aquarium is Zoo's public CAD gallery for discovering, viewing, and sharing models. Use it when you

@@ -0,0 +1,276 @@
+---
+title: Cloud Sync
+excerpt: Keep Zoo Design Studio projects available across devices while preserving local files.
+sidebarPosition: 4
+---
+
+Cloud sync keeps Zoo Design Studio projects available through your Zoo account while preserving the
+project files you work with locally.
+
+It is built around the same file-based project model as
+[Project Libraries](/docs/zoo-design-studio/features/data-management/project-libraries):
+
+- A project is still a directory with `project.toml` and at least one `.kcl` file.
+- KCL and project metadata are still readable outside Zoo Design Studio.
+- Local file changes happen first.
+- Cloud sync runs in the background and uploads or downloads project snapshots.
+
+Cloud sync is not version control. It keeps project copies available across Zoo surfaces, while Git
+or another version-control tool records intentional history and code review.
+
+<FramedImage
+  src="/documentation-assets/docs/zoo-design-studio/features/data-management/cloud-sync/cloud-sync-status.webp"
+  alt="Zoo Design Studio Home status bar showing Cloud synced"
+  aspect="520 / 60"
+  maxHeightPx={120}
+/>
+
+## How Cloud Sync Works
+
+When cloud sync is enabled, Zoo Design Studio watches project file changes and queues sync work in
+the background. Creating, editing, renaming, and deleting project files still happens locally first.
+Zoo Design Studio then reconciles those local files with the matching project in Zoo cloud.
+
+On desktop, synced projects live in a managed Personal Cloud folder on your computer. You can see
+that path in User Settings under `App` > `Libraries`, then reveal it in your file explorer.
+
+Cloud projects can appear in several states:
+
+| State | Meaning |
+| --- | --- |
+| Cloud-only | The project exists in Zoo cloud and has not been downloaded on this device yet. Opening it creates a local working copy. |
+| Cloud synced | Local files and the cloud project are up to date. |
+| Cloud sync pending | Local changes are queued for upload. |
+| Cloud syncing | Zoo Design Studio is uploading or downloading project data. |
+| Cloud sync failed | Sync could not complete and will be retried. Your local files remain available. |
+| Cloud sync blocked | Zoo Design Studio can read the cloud project but cannot upload local changes, usually because the current account does not have write access. |
+| Cloud conflict | Local and cloud data both changed since the last synced version and need manual resolution. |
+
+Failed work stays queued and is retried automatically. A downloaded project remains locally
+available after a network request fails, but a cloud-only project needs a connection before it can
+be opened.
+
+Browser working copies live in site storage. Clearing the browser's site data can remove those local
+copies and any work that has not reached `Cloud synced`.
+
+Before changing the same project on another device or browser, wait for the first device to show
+`Cloud synced`. Cloud sync is not a real-time collaboration session; if both copies change, Zoo
+Design Studio may merge independent file changes or ask you to resolve a conflict.
+
+## What Is Included in Cloud Sync
+
+Cloud sync uploads KCL, project metadata, and other project files that are not excluded.
+
+Cloud sync does not upload:
+
+- Files and folders matched by the project's `.gitignore` rules. The `.gitignore` files themselves
+  are uploaded.
+- Version-control metadata directories named `.git`, `.hg`, `.svn`, or `.jj`.
+- Zoo's internal `._meta` data or the generated project thumbnail.
+
+Binary files are included unless `.gitignore` excludes them. Cloud sync does not infer which files
+contain secrets, so exclude sensitive paths before syncing.
+
+**Important:** Excluded files are not part of the cloud project. Current versions can replace or
+remove the entire managed project folder during a remote update, automatic merge, remote deletion,
+automatic duplicate cleanup, or `Use cloud data`. This can remove local Git history, ignored files,
+and other excluded content.
+
+## Duplicate Local Copies
+
+A cloud project can have more than one local copy. This can happen if you copy a synced project
+folder in Finder or File Explorer, restore one from a backup, or keep overlapping project library
+folders that both include the same project.
+
+Zoo Design Studio tracks this as one cloud project with one or more local copies. Home picks one
+canonical copy to open and sync from, then marks extra copies with a `Duplicate copies` badge.
+
+Duplicate copies are handled conservatively:
+
+- The canonical copy is kept.
+- Extra local copies are not hidden just because they share the same cloud project ID.
+- Directory library copies are not silently deleted.
+- Zoo Design Studio may clean up an exact duplicate in the cloud library only when it can prove that
+  copy matches the clean synced version.
+- Pending, conflicted, unreadable, tombstoned, sync-excluded, or changed copies stay available for
+  review.
+
+Ignored files and version-control metadata do not make an otherwise exact extra copy divergent, so
+automatic cleanup can remove that excluded content with the duplicate folder.
+
+Use `Review duplicate copies` from the project card context menu to inspect duplicate local folders.
+You can select duplicate folders to permanently delete, and Zoo Design Studio will still keep the
+canonical folder. This review action removes selected local folders; it does not delete the cloud
+project.
+
+<FramedImage
+  src="/documentation-assets/docs/zoo-design-studio/features/data-management/cloud-sync/cloud-sync-duplicate-copies-menu.webp"
+  alt="Project card with a Duplicate copies badge and the Review duplicate copies menu action"
+  aspect="420 / 300"
+  maxHeightPx={420}
+/>
+
+## Automatic Merging
+
+Cloud sync can automatically merge simple project changes when local files and cloud files changed
+in different places after the last synced version.
+
+For example, if you edit `main.kcl` locally while another Zoo surface adds `mount.kcl` in the cloud,
+Zoo Design Studio can keep your local `main.kcl`, download the cloud-only `mount.kcl`, upload the
+combined project snapshot, and continue syncing without asking you to resolve a conflict.
+
+Automatic merging is intentionally conservative:
+
+- If only the local copy changed a file, Zoo Design Studio keeps the local file.
+- If only the cloud copy changed a file, Zoo Design Studio uses the cloud file.
+- If both copies changed the same file to the same contents, Zoo Design Studio accepts that file.
+- If both copies changed the same file differently, Zoo Design Studio shows a cloud sync conflict.
+
+Cloud sync does not perform line-by-line or semantic code merges inside a `.kcl` file. Use Git or
+another version-control tool when you need intentional history, branches, code review, or manual
+same-file merging.
+
+## Start Syncing
+
+To start syncing a local Directory project, move it to `Personal Cloud`:
+
+1. Select `Move to library` from the Command Bar, the project menu in the top bar, or the project
+   card context menu on Home.
+2. Choose the local project.
+3. Choose `Personal Cloud` as the destination library.
+4. Confirm the move.
+
+Zoo Design Studio moves the project into the cloud library and keeps a local working copy for normal
+editing. If cloud sync is enabled, it uploads the project to your Zoo account; if cloud sync is paused
+on desktop, the project remains local in that folder until you enable it again.
+
+Creating a project directly in `Personal Cloud` also starts it as a synced project. In the browser,
+Personal Cloud is the only project library, so projects are cloud-backed by default.
+
+{/* VIDEO PLACEHOLDER: Moving a Directory project to Personal Cloud and watching the sync status reach Cloud synced. */}
+
+<FramedImage
+  src="/documentation-assets/docs/zoo-design-studio/features/data-management/project-libraries/move-directory-to-personal-cloud.webp"
+  alt="Move to library review for moving a Directory project into Personal Cloud"
+  aspect="576 / 254"
+  maxHeightPx={320}
+/>
+
+## Stop Syncing
+
+To make a synced project local-only, move it from `Personal Cloud` to a Directory library:
+
+1. Select `Move to library` from the Command Bar, the project menu in the top bar, or the project
+   card context menu on Home.
+2. Choose the synced project.
+3. Choose a Directory library as the destination.
+4. Confirm the move.
+
+Zoo Design Studio disconnects the project from cloud sync and moves the files into the selected
+local library. The moved local copy is the project that remains, and future edits happen only in
+that Directory library unless you move the project back to `Personal Cloud`.
+
+**Important:** Moving a project from Personal Cloud to a Directory library deletes the remote cloud
+project before moving the remaining local folder. The cloud project is no longer available in the
+browser or on other devices. If remote deletion fails, Zoo Design Studio restores the cloud link and
+the move fails.
+
+Remote deletion happens before the filesystem move. If that later move fails, the remote project is
+not restored automatically. Back up important work before moving it out of Personal Cloud.
+
+Turning the cloud sync plugin off only pauses synchronization; it does not make a project local-only.
+A cloud-only project must first be opened and downloaded before it can be moved.
+
+{/* VIDEO PLACEHOLDER: Moving a Personal Cloud project into a Directory library to make it local-only. */}
+
+<FramedImage
+  src="/documentation-assets/docs/zoo-design-studio/features/data-management/project-libraries/move-personal-cloud-to-directory.webp"
+  alt="Move to library review for moving a Personal Cloud project into a Directory library"
+  aspect="576 / 254"
+  maxHeightPx={320}
+/>
+
+## Delete Synced Projects
+
+Deleting a cloud-backed project follows the library that owns the project card.
+
+If you delete a project from `Personal Cloud`, Zoo Design Studio deletes the cloud project. If the
+project has a local working copy on that device, the local working copy is removed too.
+
+If you delete a cloud-backed project from a Directory library, Zoo Design Studio deletes only that
+local folder. The cloud project remains in your Zoo account, and the delete dialog says that the
+cloud version will not be deleted.
+
+Keep cloud sync enabled and make sure Zoo Design Studio can reach the cloud before deleting a
+cloud-linked project. Deleting a downloaded Personal Cloud project removes its local folder before
+the remote request finishes. If that request fails, Zoo Design Studio reports the failure, but the
+local folder may already be gone and the remote project can reappear on Home.
+
+Deletion from Personal Cloud propagates to other devices. Copies with unsynced changes, or copies Zoo
+Design Studio cannot verify, are preserved and disconnected instead. Excluded files do not count as
+changes, so keep the separate backup described above.
+
+This is different from `Move to library`. Use `Move to library` when you want to change where a
+project belongs. Use delete when you want to remove the project card from its current library.
+Moving from Personal Cloud to a Directory library also deletes the remote project, but preserves and
+relocates the selected local folder.
+
+## Resolve Conflicts
+
+A cloud sync conflict happens when the local project and the cloud project both changed after the
+last synced version, and Zoo Design Studio cannot safely combine the changes automatically.
+
+When a conflict is detected:
+
+- The project card on Home shows a `Cloud conflict` badge.
+- The project breadcrumb can show a `Cloud conflict` badge while the project is open.
+- The Home status bar (bottom-left corner) shows `Cloud conflict`; select it to list conflicted projects.
+- The open project's menu (top-left corner) shows `Cloud conflict`; select it to open the dialog.
+
+Zoo Design Studio keeps your current local project as the primary project while you review the
+conflict.
+
+<FramedImage
+  src="/documentation-assets/docs/zoo-design-studio/features/data-management/cloud-sync/cloud-sync-conflict-home.webp"
+  alt="Home showing Cloud conflict on a project card and in the status bar"
+  aspect="1440 / 900"
+  maxHeightPx={460}
+/>
+
+Open the conflict dialog from the project menu or from the cloud sync status UI. The dialog compares
+the local version and the cloud version file by file.
+
+Files are labeled as:
+
+- `Changed`, when local and cloud both have the file but with different contents.
+- `Only local`, when the file exists only in the local project.
+- `Only cloud`, when the file exists only in the cloud project.
+
+Text files, including `.kcl` and Markdown files, show a side-by-side diff when possible. Large,
+binary, or non-UTF-8 files may show file metadata without an inline diff.
+
+The resolution applies to the whole project, not individual files. Choose one resolution:
+
+- `Use local data` uploads the current local project to the cloud, clears the conflict, and resumes
+  sync from the local version.
+- `Use cloud data` replaces the entire local project with the cloud version shown in the dialog,
+  clears the conflict, and resumes sync from the cloud version.
+
+If you need to combine both versions, manually copy or edit the files you want into the local
+project first, then choose `Use local data`.
+
+You may want to back up the local folder before choosing `Use cloud data`, especially if it contains ignored or
+version-control files.
+
+<FramedImage
+  src="/documentation-assets/docs/zoo-design-studio/features/data-management/cloud-sync/cloud-sync-conflict-dialog.webp"
+  alt="Cloud conflict dialog comparing changed, local-only, and cloud-only files with options to use local or cloud data"
+  aspect="1440 / 900"
+  maxHeightPx={620}
+/>
+
+## Related
+
+- [Project Libraries](/docs/zoo-design-studio/features/data-management/project-libraries)
+- [Project Browser](/docs/zoo-design-studio/features/workspace/project-browser)
+- [File Explorer](/docs/zoo-design-studio/features/workspace/file-explorer)
@@ -1,20 +1,12 @@
 ---
 title: Default Project Folder
-excerpt: Configure the default project root in Zoo Design Studio.
-sidebarPosition: 3
+excerpt: Understand how the legacy default project folder maps to Project Libraries.
+sidebarPosition: 5
 ---
 
-The Default Project Folder sets the default location for Zoo Design Studio projects.
+Project Libraries replaced the single Default Project Folder control in current Zoo Design Studio
+releases. The legacy `Project Directory` setting is no longer shown in Settings.
 
-When a folder is assigned as the `Loaded From` location, new projects are created in that directory
-by default. This helps keep ZDS projects organized in one place while still allowing you to open
-existing projects from other locations when needed.
-
-You can reassign the default folder at any time.
-
-## Behavior
-
-- Choose a default project folder.
-- New projects are created in that folder automatically.
-- The assigned folder can be changed at any time.
-- Existing projects can still be opened from other locations.
+Manage project locations under `Settings` > `User` > `App` > `Libraries`. See
+[Project Libraries](/docs/zoo-design-studio/features/data-management/project-libraries) for the current
+workflow.
@@ -7,9 +7,23 @@ sidebarPosition: 7
 Data Management covers how geometry and project files are imported, exported, versioned, and stored
 in Zoo Design Studio.
 
-This section includes
-[Import](/docs/zoo-design-studio/features/data-management/import),
-[Export](/docs/zoo-design-studio/features/data-management/export),
-[Version Control](/docs/zoo-design-studio/features/data-management/version-control),
-[Default Project Folder](/docs/zoo-design-studio/features/data-management/default-project-folder), and
-[Aquarium](/docs/zoo-design-studio/features/data-management/aquarium).
+Zoo Design Studio projects are folders of files. The main project source is human-readable text:
+KCL files for model logic and, when present, `project.toml` for project metadata. That makes projects
+portable, inspectable, syncable, and practical to version with normal developer tools.
+
+## Topics
+
+- [Import](/docs/zoo-design-studio/features/data-management/import) covers bringing CAD files,
+  models, and KCL into a project.
+- [Export](/docs/zoo-design-studio/features/data-management/export) covers writing geometry and
+  project output to other formats.
+- [Version Control](/docs/zoo-design-studio/features/data-management/version-control) covers using
+  Git and other text-based revision workflows with Zoo Design Studio projects.
+- [Aquarium](/docs/zoo-design-studio/features/data-management/aquarium) covers browser-based project
+  and data-management workflows.
+- [Project Libraries](/docs/zoo-design-studio/features/data-management/project-libraries) covers
+  organizing projects across local folders and cloud-backed libraries.
+- [Cloud Sync](/docs/zoo-design-studio/features/data-management/cloud-sync) covers syncing projects
+  through your Zoo account and resolving sync conflicts.
+- [Default Project Folder](/docs/zoo-design-studio/features/data-management/default-project-folder)
+  explains how the legacy single-folder setting maps to Project Libraries.