What syncs · Hyperclay Local docs

Hyperclay Local syncs your documents, their merge state, and their uploaded attachments with hyperclay.com, while keeping local backups, hidden files, and dependency folders on your computer only.

Documents and attachments#

Sync classifies every file in a synced folder into one of two categories based on its extension:

Category	File types and paths	How it syncs
Documents	Files ending in `.html` or `.htmlclay`	Synced as malleable documents, along with their page merge state in `.hyperclay/page-state`.
Attachments	Every other syncable file	Synced as attachments. Files uploaded from a document live in `uploads/assets-<name>/` and are linked as `/_/uploads/` paths, matching the layout on `hyperclay.com`.

The top-level uploads/ folder itself is protected: sync never deletes, renames, or moves uploads/ on the server, and restores it if removed locally.

Files and folders that never sync#

The following files and folders are always skipped on disk and ignored in the sync ledger:

Dotfiles and dot-folders: Any path segment starting with ., including .hyperclay/ (which holds local backups in .hyperclay/versions/, recovered copies in .hyperclay/recovered/, and parked conflict files in .hyperclay/conflicts/), .trash/, and .DS_Store.
Tool and legacy folders: node_modules, sites-versions, and tailwindcss.
Operating system metadata: Thumbs.db and desktop.ini.
Editor backup and swap files: Any file name ending in ~ or wrapped in #...#.
Symbolic links: Symlinks are skipped and never followed during sync snapshots.
Unreadable directories: Folders that the operating system does not allow Hyperclay Local to read are left out of sync and deletion checks.

Hyperclay Local uses this fixed ignore list; it does not read .gitignore or custom ignore files.

File size limits#

Item	Limit	What happens when exceeded
Attachments (upload)	Your `hyperclay.com` plan’s per-file upload cap	The file stays on your computer and does not upload. The folder card shows 1 file can’t sync (or `{count}` files can’t sync) and Notices shows `<file>` is stored here but can’t sync: `<size>`, and this plan allows `<limit>` with a Show File button.
Documents (upload)	`5 MiB`	A `.html` or `.htmlclay` document over `5 MiB` on `hyperclay.com` is downloaded to your computer, but marked upload-blocked so local edits to it are not re-uploaded.
Account storage	Your `hyperclay.com` plan’s total storage quota	When your account quota is full, new uploads are blocked until space is freed or your plan is upgraded.

If an attachment is blocked because of your plan’s per-file cap, Hyperclay Local remembers it. If you later shrink the file, delete it, or upgrade to a plan with a higher per-file cap, the notice clears and the file syncs automatically.

Naming and folder depth rules#

Files and folders must satisfy the naming and structure rules shared with hyperclay.com. If an item breaks a rule, sync skips it and posts a validation error in the Notices tab:

Maximum folder depth: Folders can be nested at most 5 levels deep (Folder depth cannot exceed 5 levels. Please reorganize your files into a shallower structure.).
Folder names: Must use only lowercase letters (a to z), numbers (0 to 9), hyphens (-), and underscores (_).
Document names: Files ending in .html or .htmlclay must have lowercase file names.
File name length: File names can be at most 255 bytes.
Cross-platform file names: Windows reserved names are refused, and uploaded attachment names strip characters that Windows cannot store (<, >, :, ", |, ?, *, and control characters) so every file uses the same name on macOS, Windows, Linux, and hyperclay.com.
No web-page types as attachments: Uploads into uploads/ refuse web-page file types so an attachment cannot run scripts on your folder’s origin.