docs: document push --batch, content-type routing, manifest shape

- README.md + .claude/CLAUDE.md: add push --batch / --batch-size to
  the command examples plus a callout on when the --batch path
  applies (source only; binary and plain text stay on per-file POST).
- AGENTS.md: add a contributor-facing Content-Type Routing table
  (file-class → path → headers) so anyone touching batch-upload.ts
  knows which extensions belong where. Add a Manifest Shape section
  documenting the new {localHash, remoteMtime} format and the
  migration from the pre-1.0.1 bare-string form.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 2 people

.claude/CLAUDE.md

@@ -192,13 +192,17 @@ boxel sync . --prefer-newest      # Keep newest version
 boxel sync . --delete             # Sync deletions both ways
 boxel sync . --dry-run            # Preview only
 
-boxel push ./local <url>          # One-way push (local → remote)
-boxel push ./local <url> --delete # Push and remove orphaned remote files
-boxel pull <url> ./local          # One-way pull (remote → local)
+boxel push ./local <url>                      # One-way push (local → remote)
+boxel push ./local <url> --delete             # Push and remove orphaned remote files
+boxel push ./local <url> --batch              # Atomic batch upload (10/batch default)
+boxel push ./local <url> --batch --batch-size 25  # Custom batch size
+boxel pull <url> ./local                      # One-way pull (remote → local)
 ```
 
 > **Pull writes a manifest:** After `boxel pull <url> ./local` downloads files, it automatically writes `.boxel-sync.json` so `boxel sync .` works immediately against the fresh directory. No manual step needed between pull and first sync.
 
+> **`push --batch`:** `.gts` definitions upload individually in dependency order; `.json` instances batch through `/_atomic` in groups of N. Faster for bulk pushes (50+ files). Binary files (images, fonts) and plain-text files (`.md`, `.csv`, `.yaml`) always take the per-file POST path because `/_atomic` only accepts card and source resource types.
+
 **Failed download cleanup:** When `sync` encounters files that return 500 errors (broken/corrupted on server), it will prompt you to delete them:
 ```
 ⚠️  3 file(s) failed to download (server error):

AGENTS.md

@@ -112,11 +112,34 @@ boxel gather . -s /path/to/repo
 
 ## Batch Upload API
 The CLI supports batch uploads via the `/_atomic` endpoint:
-- Used by `track --push` for efficient multi-file uploads
+- Used by `track --push` and `push --batch` for efficient multi-file uploads
 - Sorts definitions (.gts) before instances (.json) for proper indexing
 - Fallback strategy: full batch → smaller batches → individual uploads
 - See `src/lib/batch-upload.ts` for implementation
 
+### Content-type routing (since 1.0.1)
+Before sending bytes anywhere, the uploader decides which path a file takes based on extension (see `src/lib/content-type.ts`):
+
+| File class | Examples | Path | Content-Type | Accept |
+|---|---|---|---|---|
+| Compilable source | `.gts`, `.ts`, `.tsx`, `.js`, `.jsx`, `.cjs`, `.mjs`, `.css`, `.scss`, `.less`, `.sass`, `.html` | `/_atomic` (type: `source`) | per-extension MIME | `application/vnd.card+source` |
+| Card JSON | `.json` | `/_atomic` (type: `card`, fallback `source` on parse failure) | `application/json` | `application/vnd.card+source` |
+| Plain text, non-source | `.md`, `.txt`, `.csv`, `.yaml`, `.xml` | per-file POST | per-extension MIME | `*/*` |
+| Binary | `.png`, `.jpg`, `.woff`, `.pdf`, `.zip`, etc. | per-file POST | per-extension MIME or `application/octet-stream` | `*/*` |
+
+Rationale: `/_atomic` rejects anything its module compiler can't parse. Plain text and binary files need their raw bytes stored directly, which only the per-file POST endpoint does correctly.
+
+### Manifest shape (since 1.0.1)
+All three sync commands agree on one `.boxel-sync.json` shape:
+```ts
+interface SyncManifest {
+  workspaceUrl: string;
+  lastSyncTime?: number;
+  files: Record<string, { localHash: string; remoteMtime: number }>;
+}
+```
+`push.ts` migrates the pre-1.0.1 format (`files[path] = hashString`) on read. New writes always use the object form. Mirror this shape if adding a new command that touches the manifest.
+
 ## Notes for Agents Editing This Repo
 - Prefer minimal, targeted command changes in `src/commands/*.ts`.
 - Validate with local build/tests when feasible.

README.md

@@ -218,13 +218,17 @@ boxel sync . --prefer-newest      # Keep newest by timestamp
 boxel sync . --delete             # Sync deletions both ways
 boxel sync . --dry-run            # Preview only
 
-boxel push ./local <url>          # One-way push (local → remote)
-boxel push ./local <url> --delete # Push and remove orphaned remote files
-boxel pull <url> ./local          # One-way pull (remote → local)
+boxel push ./local <url>                      # One-way push (local → remote)
+boxel push ./local <url> --delete             # Push and remove orphaned remote files
+boxel push ./local <url> --batch              # Atomic batch upload (10 files per batch)
+boxel push ./local <url> --batch --batch-size 25  # Custom batch size
+boxel pull <url> ./local                      # One-way pull (remote → local)
 ```
 
 > **Note:** `boxel pull` writes `.boxel-sync.json` automatically after a fresh download, so you can run `boxel sync .` immediately against a freshly-pulled workspace with no extra setup.
 
+> **`--batch` mode** (push only): `.gts` definitions upload individually in dependency order, then `.json` instances batch through the server's `/_atomic` endpoint in groups of N. Meaningfully faster on big pushes (50+ files) and reduces UI flashing during server re-indexing. Binary files (images, fonts) and plain-text files (`.md`, `.csv`, `.yaml`) are routed to per-file POST regardless of mode, because `/_atomic` only accepts card and source resource types.
+
 **Failed download cleanup:** When `sync` encounters files that return 500 errors (broken on server), it will prompt you to delete them:
 ```
 ⚠️  3 file(s) failed to download (server error):