# What syncs

> Which files, attachments, and folders sync with hyperclay.com, what gets skipped, and the size, naming, and depth rules.

Source: https://hyperclaylocal.com/docs/what-syncs/

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](https://hyperclaylocal.com/docs/guide/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.