@magicpixelart/cli 0.5.6 → 0.5.7

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.7] — 2026-08-26
+
+### Added
+
+- **`magicpixel push`.** Two-way sync: walk `outDir`, hash local PNGs, and
+  upload changed or new sprites back to MagicPixel (`--dry-run`, `--flatten`).
+  Cloud conflicts refuse instead of overwriting; new on-disk files are adopted
+  into the library. Prune no longer deletes pending local sprites.
+- **Unity `.meta` files.** Sync writes TextureImporter `.meta` next to PNGs
+  (point filter, no compression, deterministic GUIDs). `unityPpu` (default 32)
+  and `unitySyncAll` in `magicpixel.json`. By default only artboards flagged
+  "Sync to Unity" in the editor are pulled.
+
+### Fixed
+
+- **`npx magicpixel …` dead end.** `magicpixel` is only the bin name — the
+  published package is `@magicpixelart/cli` — so hints like "run `npx
+  magicpixel init`" 404ed (`'magicpixel@*' is not in this registry`) for anyone
+  driving the CLI purely through `npx @magicpixelart/cli …`. Every user-facing
+  command hint now goes through a single `cmd()` helper that prints the short
+  `magicpixel <cmd>` form only when the package resolves from the project's
+  `node_modules`, and the always-correct `npx @magicpixelart/cli <cmd>` form
+  otherwise.
+- **Missing-config hint points at `start`.** A config-less project is now told
+  to run `start` (init + login + first sync) rather than bare `init`, which left
+  users unauthenticated with nothing on disk. `status` uses the same hint
+  (it previously hardcoded `npx @magicpixelart/cli init`).
+
 ## [0.5.6] — 2026-08-21
 
 ### Changed

package/README.md

@@ -19,7 +19,7 @@ Requires Node.js ≥ 18.
 One command, inside your project folder (the one with `package.json`):
 
 ```bash
-npx magicpixel start
+npx @magicpixelart/cli start
 ```
 
 That walks you through everything: detects your framework, writes `magicpixel.json`, prompts for your API key (paste it from [magicpixel.art/settings](https://magicpixel.art/settings) → API Keys), pulls your sprites, and tells you how to keep them fresh.
@@ -42,16 +42,16 @@ If `start` finds a `MAGICPIXEL_API_KEY` in your `.env` / `.env.local`, it offers
 ### Manual setup (advanced)
 
 ```bash
-npx magicpixel init           # writes magicpixel.json
-npx magicpixel login          # stores your key (or: export MAGICPIXEL_API_KEY=mp_live_...)
-npx magicpixel sync           # downloads changed assets
-npx magicpixel sync --watch   # keeps assets fresh while you work
+npx @magicpixelart/cli init           # writes magicpixel.json
+npx @magicpixelart/cli login          # stores your key (or: export MAGICPIXEL_API_KEY=mp_live_...)
+npx @magicpixelart/cli sync           # downloads changed assets
+npx @magicpixelart/cli sync --watch   # keeps assets fresh while you work
 ```
 
 ### Something not working?
 
 ```bash
-npx magicpixel doctor
+npx @magicpixelart/cli doctor
 ```
 
 Prints a one-screen diagnostic (CLI version, framework, outDir, key source, last sync, last error, live manifest probe). Paste it to your AI agent — it's designed to be the only context they need.
@@ -101,6 +101,7 @@ No bundler config, no runtime, no extra package.
 | `doctor` | Print a one-screen diagnostic — paste it to your AI agent when something breaks. |
 | `repair [--dry-run] [-y]` | Self-heal a broken sync: validate key → quarantine `state.json` → prune empty dirs → full re-sync. |
 | `sync [...flags]` | Fetch manifest, diff against disk, download changed assets, prune orphans. |
+| `push [--dry-run] [--flatten]` | Upload local PNG edits (and new sprites) back to MagicPixel. |
 | `add <glob>` / `remove <glob>` | Manage `include` patterns. |
 | `list` | Print matching manifest as a table. |
 | `status` | Config, last sync, diff vs remote. |
@@ -135,6 +136,8 @@ Sync is built to be cheap: a no-op run is one small manifest request, zero PNG b
 | `include`  | `string[]` | `["**/*"]`              | Globs (picomatch) matched against `folder/slug`. |
 | `exclude`  | `string[]` | `[]`                    | Globs to exclude.                                |
 | `emitIndex`| `boolean`  | `true`                  | Emit `<outDir>/index.ts` with typed asset map.   |
+| `unityPpu` | `number?`  | `32`                    | Unity only: pixels-per-unit in generated `.meta`. |
+| `unitySyncAll` | `boolean?` | `false`             | Unity only: sync every artboard, not just those flagged in the editor. |
 | `endpoint` | `string?`  | production URL          | Override the API base (testing only). Must be **HTTPS**. |
 
 State (`.magicpixel/state.json`) tracks `lastSync` (file mode `0600`). Add `.magicpixel/` to `.gitignore` (init offers to do this).

package/dist/api.js

@@ -1,6 +1,7 @@
 import { resolveEndpoint, getApiKey, CLI_VERSION } from './config.js';
-import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, } from './util/security.js';
+import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, validateEndpointUrl, } from './util/security.js';
 import { authHeaders } from './util/authHeaders.js';
+import { cmd } from './util/invoke.js';
 /**
  * Last-seen project metadata from any manifest response this process made.
  * Populated as a side-effect of `fetchManifestPage`; read by `whoami`,
@@ -38,7 +39,7 @@ export class ApiError extends Error {
 function friendly(status, body, context) {
     if (status === 401 || status === 403) {
         return (`${context}: ${status} — API key rejected.\n` +
-            `  Fix: regenerate at https://magicpixel.art/settings and re-run \`magicpixel login\`.`);
+            `  Fix: regenerate at https://magicpixel.art/settings and re-run \`${cmd('login')}\`.`);
     }
     if (status === 404) {
         return (`${context}: 404 — endpoint or asset not found.\n` +
@@ -279,3 +280,33 @@ export function retryAfterMsFromResponse(res) {
     }
     return 0;
 }
+/** Max sprites the server accepts per request (mirrors MAX_SPRITES_PER_REQUEST). */
+export const PUSH_BATCH_SIZE = 20;
+const DEFAULT_INGEST_ENDPOINT = 'https://magicpixel.art/api/public/integration/ingest';
+export function resolveIngestEndpoint() {
+    const override = process.env.MAGICPIXEL_INGEST_ENDPOINT?.trim();
+    return override ? validateEndpointUrl(override) : DEFAULT_INGEST_ENDPOINT;
+}
+/** Post one batch of sprites. Shares the transient-retry policy with pulls. */
+export async function pushSprites(sprites) {
+    const url = resolveIngestEndpoint();
+    return retryTransient('push', async () => {
+        const { headers, requestId } = buildHeaders({ 'Content-Type': 'application/json' });
+        const res = await safeFetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ sprites }),
+        });
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.ok) {
+            const data = (await res.json());
+            const results = data && typeof data === 'object' ? data.results : undefined;
+            if (!Array.isArray(results)) {
+                throw new ApiError(502, withRequestId('push: unexpected server response shape (results missing).', serverRequestId), serverRequestId);
+            }
+            return results;
+        }
+        const bodyText = await res.text();
+        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, 'push'), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+    });
+}

package/dist/commands/doctor.js

@@ -8,6 +8,7 @@ import { detectProjectKind, hasPackageJson } from '../util/framework.js';
 import { safeFetch } from '../util/security.js';
 import { authHeaders } from '../util/authHeaders.js';
 import { CLI_VERSION } from '../version.js';
+import { cmd } from '../util/invoke.js';
 export async function doctorCommand(opts = {}) {
     const report = await collectDoctorReport(opts);
     if (opts.json) {
@@ -69,18 +70,18 @@ export async function collectDoctorReport(opts = {}) {
             : await probeManifest(endpoint);
     const suggestions = [];
     if (keySource === 'none')
-        suggestions.push('Run `magicpixel login` to store your API key.');
+        suggestions.push(`Run \`${cmd('login')}\` to store your API key.`);
     if (!config)
-        suggestions.push('Run `magicpixel start` (or `magicpixel init`) to bootstrap.');
+        suggestions.push(`Run \`${cmd('start')}\` (or \`${cmd('init')}\`) to bootstrap.`);
     if (config && !watchScript && pkgFound) {
-        suggestions.push('Add a `magicpixel:watch` npm script (or run `magicpixel sync -w`) for live sync.');
+        suggestions.push(`Add a \`magicpixel:watch\` npm script (or run \`${cmd('sync')} -w\`) for live sync.`);
     }
     if (state.lastError)
-        suggestions.push('Last sync surfaced an error — run `magicpixel repair` to self-heal.');
+        suggestions.push(`Last sync surfaced an error — run \`${cmd('repair')}\` to self-heal.`);
     // Only emit network-derived suggestions when we actually probed.
     if ('ok' in network && !network.ok) {
         if (network.status === 401 || network.status === 403) {
-            suggestions.push('API rejected the key — run `magicpixel login` with a fresh key from settings.');
+            suggestions.push(`API rejected the key — run \`${cmd('login')}\` with a fresh key from settings.`);
         }
         else if (network.status === null) {
             suggestions.push('Could not reach MagicPixel — check internet/proxy, or re-run with --offline.');
@@ -197,7 +198,7 @@ export function renderDoctorReport(r) {
         ? 'environment variable (MAGICPIXEL_API_KEY)'
         : r.key.source === 'credentials-file'
             ? '.magicpixel/credentials'
-            : kleur.yellow('none — run `magicpixel login`');
+            : kleur.yellow(`none — run \`${cmd('login')}\``);
     push(`API key source:     ${sourceLabel}`);
     push(`Watch script:       ${r.watchScript ? `"${r.watchScript}"` : kleur.dim('not configured')}`);
     push(`Last sync:          ${r.state.lastSync ? new Date(r.state.lastSync).toLocaleString() : kleur.dim('never')}`);
@@ -211,7 +212,7 @@ export function renderDoctorReport(r) {
     if ('skipped' in r.network) {
         const reason = r.network.skipped === 'offline'
             ? 'skipped (--offline)'
-            : 'skipped (no API key — run `magicpixel login`)';
+            : `skipped (no API key — run \`${cmd('login')}\`)`;
         push(`Network probe:      ${kleur.dim(reason)}`);
     }
     else if (r.network.ok) {

package/dist/commands/init.js

@@ -8,6 +8,7 @@ import { configPath, defaultConfig, saveConfig } from '../config.js';
 import { detectProjectKind, suggestOutDir, hasPackageJson, isStaticOutDir, supportsTypedIndex, isEngineKind, } from '../util/framework.js';
 import { assertSafeOutDir } from '../util/security.js';
 import { atomicWrite } from '../util/atomicWrite.js';
+import { cmd } from '../util/invoke.js';
 const WATCH_SCRIPT_NAME = 'magicpixel:watch';
 const WATCH_SCRIPT_CMD = 'magicpixel sync --watch';
 export async function initCommand(opts) {
@@ -100,13 +101,13 @@ export async function initCommand(opts) {
     if (interactive) {
         console.log();
         console.log(kleur.bold('Next:'));
-        console.log(`  1. ${kleur.dim('magicpixel login')}    ${kleur.dim('# paste your key from https://magicpixel.art/settings')}`);
-        console.log(`  2. ${kleur.dim('magicpixel sync')}     ${kleur.dim('# downloads your assets')}`);
+        console.log(`  1. ${kleur.dim(cmd('login'))}    ${kleur.dim('# paste your key from https://magicpixel.art/settings')}`);
+        console.log(`  2. ${kleur.dim(cmd('sync'))}     ${kleur.dim('# downloads your assets')}`);
         if (watchScriptAdded) {
             console.log(`  3. ${kleur.dim('npm run')} ${WATCH_SCRIPT_NAME}    ${kleur.dim('# keeps assets fresh while you edit')}`);
         }
         else {
-            console.log(`  3. ${kleur.dim('npx')} magicpixel sync --watch    ${kleur.dim('# keeps assets fresh while you edit')}`);
+            console.log(`  3. ${kleur.dim(`${cmd('sync')} --watch`)}    ${kleur.dim('# keeps assets fresh while you edit')}`);
         }
         console.log();
     }

package/dist/commands/push.js

@@ -0,0 +1,183 @@
+/**
+ * `magicpixel push` — disk → MagicPixel (the Unity → MagicPixel half of
+ * two-way sync).
+ *
+ * Walks `outDir`, hashes every PNG, and sends the ones that changed (or are
+ * brand new on disk) to `POST /api/public/integration/ingest`:
+ *
+ *   - known key + changed sha → write back into that artboard, using the sha
+ *     the CLI last pulled as the conflict baseline. If the cloud moved on the
+ *     server refuses with `conflict` and nothing is lost.
+ *   - unknown key            → adopt: the server mirrors the disk folders into
+ *     the library and appends/creates the document.
+ */
+import kleur from 'kleur';
+import ora from 'ora';
+import { mkdir, readFile, rename } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { relative, resolve } from 'node:path';
+import { loadConfig, loadState, saveState } from '../config.js';
+import { PUSH_BATCH_SIZE, pushSprites } from '../api.js';
+import { fileSha256 } from '../util/hash.js';
+import { assetDiskPathFromKey, walkOutDirPngs } from '../util/paths.js';
+import { planPush } from '../util/pushPlan.js';
+import { cmd } from '../util/invoke.js';
+export async function pushCommand(opts) {
+    const config = await loadConfig();
+    const state = await loadState();
+    const spinner = ora('Scanning local sprites…').start();
+    const disk = await walkOutDirPngs(config.outDir);
+    const candidates = [];
+    for (const asset of disk) {
+        const sha = await fileSha256(asset.abs);
+        if (!sha)
+            continue;
+        candidates.push({
+            key: asset.key,
+            segments: asset.key.split('/'),
+            diskSha256: sha,
+        });
+    }
+    const actions = planPush(candidates, state.synced, { flatten: opts.flatten });
+    const skipped = actions.filter((a) => a.kind === 'skip' && a.reason !== 'legacy').length;
+    const legacy = actions.filter((a) => a.kind === 'skip' && a.reason === 'legacy');
+    const flattenBlocked = actions.filter((a) => a.kind === 'needs-flatten');
+    const sendable = actions.filter((a) => a.kind === 'update' || a.kind === 'adopt');
+    spinner.succeed(`Local sprites: ${candidates.length} · to push ${sendable.length} · unchanged ${skipped}`);
+    if (legacy.length > 0) {
+        console.log();
+        console.log(kleur.yellow(`! ${legacy.length} sprite${legacy.length === 1 ? '' : 's'} came from a legacy single-image file — skipped.`));
+        console.log(kleur.dim(`  Fix: open the file in MagicPixel and save it once, then re-run \`${cmd('sync')}\`.`));
+    }
+    if (flattenBlocked.length > 0) {
+        console.log();
+        console.log(kleur.yellow(`! ${flattenBlocked.length} sprite${flattenBlocked.length === 1 ? '' : 's'} would flatten a multi-layer artboard — skipped.`));
+        for (const a of flattenBlocked.slice(0, 10)) {
+            console.log(kleur.dim(`    ${a.key} (${'layers' in a ? a.layers : '?'} layers)`));
+        }
+        console.log(kleur.dim('  Fix: re-run with --flatten to replace them with the flat disk image.'));
+    }
+    if (sendable.length === 0) {
+        console.log(kleur.green('✓ nothing to push.'));
+        return;
+    }
+    if (opts.dryRun) {
+        console.log();
+        for (const a of sendable) {
+            const verb = a.kind === 'update' ? kleur.yellow('~') : kleur.green('+');
+            console.log(`  ${verb} ${a.key}${a.kind === 'adopt' ? kleur.dim(' (new)') : ''}`);
+        }
+        console.log(kleur.dim('--dry-run: nothing sent.'));
+        return;
+    }
+    const outRoot = resolve(process.cwd(), config.outDir);
+    const shaByKey = new Map(candidates.map((c) => [c.key, c.diskSha256]));
+    const sprites = [];
+    for (const a of sendable) {
+        const abs = resolve(outRoot, `${a.key}.png`);
+        const pngBase64 = (await readFile(abs)).toString('base64');
+        const diskSha256 = shaByKey.get(a.key);
+        if (a.kind === 'update') {
+            sprites.push({
+                key: a.key,
+                pngBase64,
+                diskSha256,
+                assetId: a.assetId,
+                layerIdx: a.layerIdx,
+                baseSha256: a.baseSha256,
+                flatten: opts.flatten === true,
+            });
+        }
+        else if (a.kind === 'adopt') {
+            sprites.push({ key: a.key, pngBase64, diskSha256, path: a.path, pathNames: a.pathNames, name: a.name });
+        }
+    }
+    const progress = ora(`Pushing 0/${sprites.length}…`).start();
+    const results = [];
+    for (let i = 0; i < sprites.length; i += PUSH_BATCH_SIZE) {
+        const batch = sprites.slice(i, i + PUSH_BATCH_SIZE);
+        const batchResults = await pushSprites(batch);
+        results.push(...batchResults);
+        progress.text = `Pushing ${Math.min(i + batch.length, sprites.length)}/${sprites.length}…`;
+    }
+    const counts = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0 };
+    const nextSynced = { ...(state.synced ?? {}) };
+    for (const r of results) {
+        counts[r.status] = (counts[r.status] ?? 0) + 1;
+        // The server may have stored the document under a different slug than the
+        // disk folder (collision suffix, slugified name). Move the local files to
+        // the key the manifest will report, or the next `sync` downloads a second
+        // copy alongside this one.
+        const stateKey = r.cloudKey && r.cloudKey !== r.key ? r.cloudKey : r.key;
+        if (stateKey !== r.key && (r.status === 'created' || r.status === 'updated')) {
+            await renameLocalSprite(config.outDir, r.key, stateKey);
+        }
+        // Store the sha the cloud now reports so the next `push` is a no-op and
+        // the next `sync` doesn't see a phantom change.
+        if ((r.status === 'created' || r.status === 'updated' || r.status === 'unchanged') && r.assetId && r.sha256) {
+            if (stateKey !== r.key)
+                delete nextSynced[r.key];
+            nextSynced[stateKey] = {
+                assetId: r.assetId,
+                layerIdx: typeof r.layerIdx === 'number' ? r.layerIdx : (nextSynced[stateKey]?.layerIdx ?? 0),
+                sha256: r.sha256,
+                // A push always leaves the artboard single-layer (the flat disk image).
+                layers: 1,
+            };
+        }
+    }
+    await saveState({ ...state, synced: nextSynced });
+    const failed = counts.conflict + counts.error;
+    const summary = `created ${counts.created}, updated ${counts.updated}, unchanged ${counts.unchanged}` +
+        (counts.conflict ? `, conflicts ${counts.conflict}` : '') +
+        (counts.error ? `, errors ${counts.error}` : '');
+    if (failed)
+        progress.warn(`Push finished with issues. ${summary}`);
+    else
+        progress.succeed(`Pushed. ${summary}`);
+    for (const r of results) {
+        if (r.status === 'conflict') {
+            console.log(`  ${kleur.yellow('!')} ${r.key}: ${conflictHint(r.reason)}`);
+        }
+        else if (r.status === 'error') {
+            console.log(`  ${kleur.red('!')} ${r.key}: ${r.message ?? 'push failed'}`);
+        }
+    }
+    if (counts.created > 0) {
+        console.log(kleur.dim(`  ${counts.created} new sprite${counts.created === 1 ? '' : 's'} now live in your MagicPixel library ` +
+            `(folders mirrored from ${relative(process.cwd(), outRoot)}).`));
+    }
+    if (failed)
+        process.exitCode = 1;
+}
+function conflictHint(reason) {
+    switch (reason) {
+        case 'cloud-changed':
+            return `changed in MagicPixel since the last sync — run \`${cmd('sync')}\` first, then re-push.`;
+        case 'would-flatten':
+            return 'artboard has multiple layers or frames — re-run with --flatten to replace it.';
+        case 'legacy-document':
+            return 'document predates layer storage — open and save it once in MagicPixel.';
+        case 'not-found':
+            return `artboard no longer exists in MagicPixel — run \`${cmd('sync')}\` to refresh.`;
+        default:
+            return `conflict — run \`${cmd('sync')}\` and try again.`;
+    }
+}
+/**
+ * Move a pushed sprite (and its `.meta` sidecar) to the disk path matching the
+ * key the cloud assigned. Best effort: a failed move only means the next sync
+ * re-downloads the sprite under its cloud name.
+ */
+async function renameLocalSprite(outDir, fromKey, toKey) {
+    const from = assetDiskPathFromKey(outDir, fromKey);
+    const to = assetDiskPathFromKey(outDir, toKey);
+    try {
+        await mkdir(dirname(to), { recursive: true });
+        await rename(from, to);
+        await rename(`${from}.meta`, `${to}.meta`).catch(() => { });
+    }
+    catch {
+        // Leave the file where it is; sync reconciles.
+    }
+}

package/dist/commands/repair.js

@@ -8,9 +8,10 @@ import { loadConfig, statePath, getApiKey } from '../config.js';
 import { assertKeyValid } from '../util/auth.js';
 import { listEmptyDirs, pruneEmptyDirs } from '../util/paths.js';
 import { syncCommand } from './sync.js';
+import { cmd } from '../util/invoke.js';
 /**
  * One-shot self-healing command. Runs the standard "turn it off and on
- * again" recovery sequence so support can say "run `npx magicpixel repair`":
+ * again" recovery sequence so support can say "run `npx @magicpixelart/cli repair`":
  *
  *   1. Validate the stored API key.
  *   2. Quarantine `state.json` so the next sync re-derives everything.
@@ -117,7 +118,7 @@ export async function repairCommand(opts = {}) {
         console.log(kleur.dim('     (state was not reset — this will run a normal full sync, not a recovery)'));
     }
     if (opts.dryRun) {
-        console.log(`     ${kleur.dim('would run `magicpixel sync --full` (skipped in --dry-run)')}`);
+        console.log(`     ${kleur.dim(`would run \`${cmd('sync')} --full\` (skipped in --dry-run)`)}`);
         console.log();
         if (skippedStep2) {
             console.log(kleur.yellow('! repair plan would skip the state reset. Re-run with --yes to apply it.'));
@@ -137,7 +138,7 @@ export async function repairCommand(opts = {}) {
     await syncCommand({ full: true, prune: true });
     console.log();
     if ((process.exitCode ?? 0) > exitBefore) {
-        console.log(kleur.yellow('! repair completed with errors — re-run `magicpixel sync` to retry the failed downloads.'));
+        console.log(kleur.yellow(`! repair completed with errors — re-run \`${cmd('sync')}\` to retry the failed downloads.`));
     }
     else {
         console.log(kleur.green('✓ repair complete.'));

package/dist/commands/start.js

@@ -10,10 +10,11 @@ import { findKeyInDotenv, readCredentialsSync, writeCredentials } from '../util/
 import { initCommand } from './init.js';
 import { loginCommand } from './login.js';
 import { syncCommand } from './sync.js';
+import { cmd } from '../util/invoke.js';
 /**
  * One-command bootstrap for new users. Runs init → key prompt → first sync →
  * prints copy-pasteable watch instructions. Designed so a non-technical user
- * can paste `npx magicpixel start` and end up with sprites on disk and a watch
+ * can paste `npx @magicpixelart/cli start` and end up with sprites on disk and a watch
  * script ready to run.
  */
 export async function startCommand(opts = {}) {
@@ -24,8 +25,8 @@ export async function startCommand(opts = {}) {
     if (!hasPackageJson()) {
         const kind = await detectProjectKind();
         if (isEngineKind(kind)) {
-            console.log(kleur.yellow(`  Detected ${kind}. \`magicpixel start\` is JS-only; run ` +
-                '`npx magicpixel init && npx magicpixel login && npx magicpixel sync --watch` instead.'));
+            console.log(kleur.yellow(`  Detected ${kind}. \`${cmd('start')}\` is JS-only; run ` +
+                `\`${cmd('init')} && ${cmd('login')} && ${cmd('sync')} --watch\` instead.`));
             return;
         }
         console.log(kleur.yellow('  MagicPixel needs a JavaScript project (package.json) to sync into.\n' +
@@ -46,7 +47,7 @@ export async function startCommand(opts = {}) {
             console.log(kleur.yellow(`  Existing magicpixel.json is invalid:`));
             for (const line of msg.split('\n'))
                 console.log(kleur.yellow(`    ${line}`));
-            console.log(kleur.dim('  Re-run `npx magicpixel start --force` to overwrite it, or fix the file by hand.'));
+            console.log(kleur.dim(`  Re-run \`${cmd('start')} --force\` to overwrite it, or fix the file by hand.`));
             return;
         }
     }
@@ -84,7 +85,7 @@ export async function startCommand(opts = {}) {
     console.log();
     if (firstSyncFailed) {
         console.log(kleur.yellow('! first sync completed with errors.'));
-        console.log(kleur.dim('  Re-run `npx magicpixel sync` to retry the failed downloads, or `npx magicpixel doctor` to diagnose.'));
+        console.log(kleur.dim(`  Re-run \`${cmd('sync')}\` to retry the failed downloads, or \`${cmd('doctor')}\` to diagnose.`));
     }
     else {
         console.log(kleur.bold('You\'re set up. ✨'));
@@ -95,11 +96,11 @@ export async function startCommand(opts = {}) {
         console.log(`  ${kleur.green('▶')} ${kleur.bold('npm run magicpixel:watch')}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
     }
     else {
-        console.log(`  ${kleur.green('▶')} ${kleur.bold('npx magicpixel sync --watch')}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
+        console.log(`  ${kleur.green('▶')} ${kleur.bold(`${cmd('sync')} --watch`)}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
     }
     console.log();
     if (await hasDevScript()) {
-        const watchCmd = hasWatch ? 'npm run magicpixel:watch' : 'npx magicpixel sync --watch';
+        const watchCmd = hasWatch ? 'npm run magicpixel:watch' : `${cmd('sync')} --watch`;
         console.log(kleur.dim('  Tip: run your dev server and the watcher together with'));
         console.log(kleur.dim(`       \`npx concurrently "npm run dev" "${watchCmd}"\``));
         console.log();

package/dist/commands/status.js

@@ -5,6 +5,7 @@ import { fileSha256 } from '../util/hash.js';
 import { assetDiskPath } from '../util/paths.js';
 import { readKeyForDisplay } from '../util/credentials.js';
 import { createLimit } from '../util/limit.js';
+import { cmd } from '../util/invoke.js';
 export async function statusCommand() {
     // Config is optional — a brand-new user can `magicpixel status` to inspect
     // their key/env before bothering with init. Mirrors `whoami` / `login`.
@@ -25,7 +26,7 @@ export async function statusCommand() {
     }
     else {
         console.log(kleur.yellow(`  magicpixel.json: ${configErr ?? 'missing'}`));
-        console.log(kleur.dim(`  Run \`npx magicpixel init\` to create one.`));
+        console.log(kleur.dim(`  Run \`${cmd('start')}\` to create one.`));
     }
     console.log();
     const state = await loadState();
@@ -40,7 +41,7 @@ export async function statusCommand() {
     // env var and falsely reported "key not set" for logged-in users.
     const stored = readKeyForDisplay();
     if (!stored) {
-        console.log(kleur.red('  no API key — run `magicpixel login` or set MAGICPIXEL_API_KEY'));
+        console.log(kleur.red(`  no API key — run \`${cmd('login')}\` or set MAGICPIXEL_API_KEY`));
         return;
     }
     const sourceLabel = stored.source === 'env' ? 'env (MAGICPIXEL_API_KEY)' : 'file (.magicpixel/credentials)';

package/dist/commands/sync.js

@@ -11,11 +11,16 @@ import { assetDiskPath, assetDiskPathFromKey, pruneEmptyDirs, walkOutDirPngs } f
 import { createLimit } from '../util/limit.js';
 import { emitTypedIndex, ensureAgentsDoc, scanDiskAssets } from '../util/emitIndex.js';
 import { assertPathInsideRoot } from '../util/security.js';
+import { detectProjectKind } from '../util/framework.js';
+import { DEFAULT_UNITY_PPU, writeMissingUnityMetas } from '../util/unityMeta.js';
+import { filterUnityManifest } from '../util/unityFilter.js';
+import { selectFullSyncOrphans } from '../util/prunePolicy.js';
 import { runTmpJanitor } from '../util/tmpJanitor.js';
 import { friendlyFsError } from '../util/errors.js';
 import { maxIsoTimestamp } from '../util/iso.js';
 import { formatBytes } from '../util/format.js';
 import { computePreviousKeyOrphans } from '../util/previousKeyOrphans.js';
+import { cmd } from '../util/invoke.js';
 export async function syncCommand(opts) {
     // Sweep any leaked `<file>.<pid>.<hex>.tmp` files left behind by a prior
     // crashed/killed CLI run before they pile up. Runs once per CLI invocation
@@ -180,14 +185,14 @@ async function watchLoop(opts) {
                     // support thread and we can correlate against edge function logs.
                     const idSuffix = apiErr?.requestId ? kleur.dim(` (request id: ${apiErr.requestId})`) : '';
                     console.log(`${kleur.dim(timestamp())} ${kleur.red('✗')} Your key looks invalid or rotated.${idSuffix}`);
-                    console.log(kleur.dim('   Fix: run `magicpixel login` (this watcher will keep retrying every 30s).'));
+                    console.log(kleur.dim(`   Fix: run \`${cmd('login')}\` (this watcher will keep retrying every 30s).`));
                 }
                 pausedForAuth = true;
                 consecutiveAuthFailures = decision.consecutiveAuthFailures;
                 backoffSec = decision.nextBackoffSec;
                 if (decision.giveUp) {
                     console.log(`${kleur.dim(timestamp())} ${kleur.red('✗')} Giving up after ${MAX_AUTH_FAILURES} consecutive auth failures.`);
-                    console.log(kleur.dim('   Fix: run `magicpixel login` with a fresh key, then restart the watcher.'));
+                    console.log(kleur.dim(`   Fix: run \`${cmd('login')}\` with a fresh key, then restart the watcher.`));
                     // Surface this to /admin/errors — persistent watcher auth failure
                     // means a key is mass-rejected (revoked, project deleted, edge
                     // misconfig) and we want visibility without waiting for a support
@@ -337,6 +342,63 @@ async function runOnce(opts, runOpts = {}) {
         spinner?.fail('Manifest fetch failed');
         throw e;
     }
+    // Unity projects sync only the artboards flagged "Sync to Unity" in the
+    // editor (parity with the in-app sync button). `unitySyncAll: true` in
+    // magicpixel.json opts back into everything.
+    const projectKind = await detectProjectKind();
+    // Files whose artboard is no longer flagged for Unity. Deleted even in
+    // incremental mode: un-checking the box in the editor must actually remove
+    // the sprite from the game project, not leave a stale copy behind.
+    const deselectedPaths = [];
+    // Sprites whose "Sync to Unity" flag the server omitted. Not downloaded
+    // (strict opt-in) but explicitly shielded from pruning: a transient server
+    // response must never delete art from someone's game project.
+    const unknownFlagPaths = new Set();
+    if (projectKind === 'Unity') {
+        const filtered = filterUnityManifest(manifest, { syncAll: config.unitySyncAll });
+        if (filtered.unknown.length > 0) {
+            console.log(kleur.yellow(`! ${filtered.unknown.length} artboard${filtered.unknown.length === 1 ? '' : 's'} came back without a "Sync to Unity" flag — skipped (existing files kept).`));
+            console.log(kleur.dim(`  Fix: re-run \`${cmd('sync')}\` in a moment, or upgrade with \`npm i -D @magicpixelart/cli@latest\`.`));
+        }
+        const unknownSet = new Set(filtered.unknown);
+        for (const entry of manifest) {
+            if (filtered.entries.includes(entry))
+                continue;
+            const p = assetDiskPath(config.outDir, entry);
+            if (unknownSet.has(entry)) {
+                unknownFlagPaths.add(p);
+                continue;
+            }
+            if (existsSync(p))
+                deselectedPaths.push(p);
+        }
+        if (filtered.noneFlagged) {
+            // Every artboard is explicitly opted out. Pruning here would delete the
+            // user's whole sprite folder off the back of an unchecked box, so bail
+            // out with a hint instead.
+            if (verbose) {
+                console.log();
+                console.log(kleur.yellow('! No artboards are flagged "Sync to Unity" — nothing to sync.'));
+                console.log(kleur.dim('  Fix: right-click an artboard in MagicPixel → "Sync to Unity",'));
+                console.log(kleur.dim('  or set "unitySyncAll": true in magicpixel.json to sync everything.'));
+            }
+            return {
+                added: [],
+                modified: [],
+                removed: [],
+                unchanged: 0,
+                failed: 0,
+                bytesIn: 0,
+                bytesSaved: 0,
+                renamed: [],
+            };
+        }
+        const skipped = manifest.length - filtered.entries.length;
+        manifest = filtered.entries;
+        if (verbose && skipped > 0) {
+            console.log(kleur.dim(`  unity → ${skipped} artboard${skipped === 1 ? '' : 's'} not flagged for sync (skipped)`));
+        }
+    }
     // Detect renames: same id, different key vs prior snapshot.
     const renamed = [];
     for (const entry of manifest) {
@@ -385,8 +447,29 @@ async function runOnce(opts, runOpts = {}) {
     // still gated on `!since` to preserve incremental-mode safety (we never
     // delete files outside what the current manifest delta touches).
     const localPngs = await walkOutDirPngs(config.outDir);
+    // Sprites created in Unity (or any PNG we never pulled) are pending a
+    // `magicpixel push`, not orphans — see prunePolicy.ts.
+    let pendingPush = [];
     if (!since) {
-        orphans = localPngs.map((a) => a.abs).filter((p) => !remoteDiskPaths.has(p));
+        const trackedPaths = new Set(Object.keys(state.synced ?? {})
+            .concat(Object.values(previousAssets))
+            .map((key) => {
+            try {
+                return assetDiskPathFromKey(config.outDir, key);
+            }
+            catch {
+                return '';
+            }
+        })
+            .filter(Boolean));
+        const policy = selectFullSyncOrphans({
+            localPaths: localPngs.map((a) => a.abs),
+            remoteDiskPaths,
+            protectedPaths: unknownFlagPaths,
+            isTracked: (p) => trackedPaths.has(p),
+        });
+        orphans = policy.orphans;
+        pendingPush = policy.pendingPush;
     }
     // Heuristic-rename fallback for incremental mode.
     //
@@ -440,6 +523,10 @@ async function runOnce(opts, runOpts = {}) {
     const orphanSet = new Set(orphans);
     for (const p of renameStalePaths)
         orphanSet.add(p);
+    // Un-checked "Sync to Unity" artboards: their PNG (and .meta) leaves the
+    // Unity project on the next sync, incremental or not.
+    for (const p of deselectedPaths)
+        orphanSet.add(p);
     // Server-side rename history. Each manifest entry carries the composite
     // keys this row was previously emitted under (populated by the editor when
     // a doc/artboard is renamed). For each prior key whose file is still on
@@ -638,6 +725,19 @@ async function runOnce(opts, runOpts = {}) {
         else
             progress.warn(`Downloaded ${downloaded}, failed ${result.failed} (${formatBytes(result.bytesIn)})`);
     }
+    // Unity: write pixel-art-correct `.meta` sidecars so sprites import with
+    // point filtering / no compression instead of Unity's blurry defaults —
+    // parity with the in-app "Sync to Unity" button. Only missing sidecars are
+    // written, so importer settings the user tweaked in Unity are preserved.
+    if (projectKind === 'Unity') {
+        const meta = await writeMissingUnityMetas(manifest.map((entry) => ({ id: entry.id, pngPath: pathFor(entry) })), config.unityPpu ?? DEFAULT_UNITY_PPU);
+        if (verbose && meta.written > 0) {
+            console.log(kleur.dim(`  unity → ${meta.written} .meta file${meta.written === 1 ? '' : 's'} written`));
+        }
+        if (verbose && meta.failed > 0) {
+            console.log(kleur.yellow(`  ! ${meta.failed} .meta file${meta.failed === 1 ? '' : 's'} could not be written — Unity will use default import settings.`));
+        }
+    }
     // Prune (now default — pass --no-prune to opt out).
     if (shouldPrune && orphans.length > 0) {
         const outRoot = resolve(process.cwd(), config.outDir);
@@ -645,6 +745,9 @@ async function runOnce(opts, runOpts = {}) {
             assertPathInsideRoot(p, outRoot, 'outDir');
             try {
                 await unlink(p);
+                // Unity sidecar follows its PNG — a stranded .meta shows up in Unity
+                // as a missing-asset warning.
+                await unlink(`${p}.meta`).catch(() => { });
                 const relPath = relative(outRoot, p).replace(/\\/g, '/');
                 const key = relPath.endsWith('.png') ? relPath.slice(0, -4) : relPath;
                 result.removed.push(key);
@@ -708,7 +811,36 @@ async function runOnce(opts, runOpts = {}) {
                 delete nextAssets[id];
         }
     }
-    const nextState = { ...state, assets: nextAssets };
+    // Address book for `magicpixel push`: composite key → artboard + the sha we
+    // just put on disk. Keyed by key (not id) so a disk walk can look it up
+    // without re-fetching the manifest. Renamed/pruned keys are dropped so a
+    // stale entry can never send an edit to the wrong artboard.
+    const nextSynced = { ...(state.synced ?? {}) };
+    for (const r of renamed)
+        delete nextSynced[r.oldKey];
+    for (const key of result.removed)
+        delete nextSynced[key];
+    for (const entry of manifest) {
+        if (!entry.asset_id)
+            continue;
+        const sha = entry.sha256 ?? (await fileSha256(pathFor(entry)));
+        if (!sha)
+            continue;
+        // Legacy single-PNG rows have no artboard address (`layer_idx: -1`). Record
+        // them anyway, flagged, so `push` skips them with a hint instead of
+        // adopting the same art as a second document.
+        if (typeof entry.layer_idx !== 'number' || entry.layer_idx < 0) {
+            nextSynced[entry.key] = { assetId: entry.asset_id, layerIdx: 0, sha256: sha, legacy: true };
+            continue;
+        }
+        nextSynced[entry.key] = {
+            assetId: entry.asset_id,
+            layerIdx: entry.layer_idx,
+            sha256: sha,
+            ...(typeof entry.layer_count === 'number' ? { layers: entry.layer_count } : {}),
+        };
+    }
+    const nextState = { ...state, assets: nextAssets, synced: nextSynced };
     if (result.failed === 0) {
         // Advance the cursor to the newest row we actually observed, NOT the
         // wall-clock time the sync started. Using startedAt silently skipped
@@ -785,6 +917,11 @@ async function runOnce(opts, runOpts = {}) {
         printChanges(result, '  ', { includeRenames: renamed.length === 0 });
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
+        if (pendingPush.length > 0) {
+            console.log();
+            console.log(kleur.yellow(`! ${pendingPush.length} local sprite${pendingPush.length === 1 ? '' : 's'} ${pendingPush.length === 1 ? 'is' : 'are'} not in MagicPixel yet — kept on disk.`));
+            console.log(kleur.dim(`  Fix: run \`${cmd('push')}\` to add them to your library.`));
+        }
     }
     if (result.failed)
         process.exitCode = 1;

package/dist/config.js

@@ -5,6 +5,7 @@ import { assertSafeOutDir, MAX_GLOB_LEN, validateEndpointUrl } from './util/secu
 import { readCredentialsSync } from './util/credentials.js';
 import { friendlyFsError } from './util/errors.js';
 import { atomicWrite } from './util/atomicWrite.js';
+import { cmd } from './util/invoke.js';
 const CONFIG_FILENAME = 'magicpixel.json';
 const STATE_DIR = '.magicpixel';
 const STATE_FILENAME = 'state.json';
@@ -25,7 +26,7 @@ export async function loadConfig(cwd = process.cwd()) {
     const path = configPath(cwd);
     if (!existsSync(path)) {
         throw new Error(`No ${CONFIG_FILENAME} found in ${cwd}.\n` +
-            `  Fix: run \`npx magicpixel init\` to create one.`);
+            `  Fix: run \`${cmd('start')}\` — it creates the config, logs you in, and runs the first sync.`);
     }
     const raw = await readFile(path, 'utf8');
     let parsed;
@@ -66,12 +67,25 @@ export async function loadConfig(cwd = process.cwd()) {
         }
         emitIndex = parsed.emitIndex;
     }
+    let unityPpu;
+    if (parsed.unityPpu !== undefined) {
+        if (typeof parsed.unityPpu !== 'number' ||
+            !Number.isFinite(parsed.unityPpu) ||
+            parsed.unityPpu <= 0 ||
+            parsed.unityPpu > 4096) {
+            throw new Error(`${CONFIG_FILENAME}: "unityPpu" must be a number between 1 and 4096.\n` +
+                `  Fix: set "unityPpu": 32 (or remove the field to use the default).`);
+        }
+        unityPpu = Math.round(parsed.unityPpu);
+    }
     return {
         outDir,
         include,
         exclude,
         endpoint,
         emitIndex,
+        unityPpu,
+        unitySyncAll: parsed.unitySyncAll === true ? true : undefined,
     };
 }
 const MAX_GLOBS = 64;
@@ -112,7 +126,7 @@ export async function saveConfig(config, cwd = process.cwd()) {
         throw friendlyFsError(e, {
             operation: 'Saving magicpixel.json',
             path,
-            hint: 'magicpixel.json holds your sync config — without it `magicpixel sync` can\'t run.',
+            hint: `magicpixel.json holds your sync config — without it \`${cmd('sync')}\` can't run.`,
         });
     }
 }
@@ -196,7 +210,7 @@ export function getApiKey() {
         throw new Error('No MagicPixel API key found.\n' +
             '  Fix:\n' +
             '    1. Get a key at https://magicpixel.art/settings (API Keys).\n' +
-            '    2. Run `magicpixel login` (or `export MAGICPIXEL_API_KEY=mp_live_...`).\n' +
+            `    2. Run \`${cmd('login')}\` (or \`export MAGICPIXEL_API_KEY=mp_live_...\`).\n` +
             '    3. Re-run the command.');
     }
     // Env vars from shells routinely smuggle in stray quotes / whitespace; the
@@ -209,7 +223,7 @@ export function getApiKey() {
     }
     if (!/^mp_(live|test)_[a-f0-9]{64}$/.test(trimmed)) {
         throw new Error(`MagicPixel API key does not look right (expected mp_live_… or mp_test_…).\n` +
-            `  Fix: run \`magicpixel login\` and paste a fresh key from https://magicpixel.art/settings.`);
+            `  Fix: run \`${cmd('login')}\` and paste a fresh key from https://magicpixel.art/settings.`);
     }
     return trimmed;
 }

package/dist/index.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import kleur from 'kleur';
 import { initCommand } from './commands/init.js';
 import { syncCommand } from './commands/sync.js';
+import { pushCommand } from './commands/push.js';
 import { addCommand } from './commands/add.js';
 import { removeCommand } from './commands/remove.js';
 import { listCommand } from './commands/list.js';
@@ -89,6 +90,13 @@ program
     .option('-c, --concurrency <n>', 'Parallel downloads (1–16, default 6)', parseConcurrency)
     .addHelpText('after', '\nExamples:\n  $ magicpixel sync                # incremental sync\n  $ magicpixel sync --full         # ignore lastSync, re-check everything\n  $ magicpixel sync -w             # watch mode (2s; adaptive idle backoff; exit 2 after 5 auth failures)\n')
     .action(wrap("sync", async (opts) => syncCommand(opts)));
+program
+    .command('push')
+    .description('Upload local sprite edits back to MagicPixel (two-way sync)')
+    .option('--dry-run', 'Print what would be pushed without sending anything')
+    .option('--flatten', 'Allow replacing multi-layer artboards with the flat local image')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel push --dry-run      # see what changed on disk\n  $ magicpixel push                # send local edits + new sprites\n')
+    .action(wrap("push", async (opts) => pushCommand(opts)));
 program
     .command('add <glob>')
     .description('Append a glob pattern to include')

package/dist/util/emitIndex.js

@@ -5,6 +5,7 @@ import { assertSafeAssetSegments } from './security.js';
 import { atomicWrite } from './atomicWrite.js';
 import { walkOutDirPngs } from './paths.js';
 import { isStaticOutDir } from './framework.js';
+import { cmd } from './invoke.js';
 const AGENT_HEADER = [
     '// 👋 AI agents: import sprites by key, e.g.',
     '//   import { MagicPixelAssets } from "<this-dir>";',
@@ -57,7 +58,7 @@ export async function emitTypedIndex(outDir, entries, cwd = process.cwd()) {
     }
     const lines = [
         '// AUTOGENERATED by @magicpixelart/cli. Do not edit.',
-        '// Re-runs of `magicpixel sync` overwrite this file.',
+        `// Re-runs of \`${cmd('sync')}\` overwrite this file.`,
         '//',
         AGENT_HEADER,
         '',
@@ -185,7 +186,7 @@ function renderAgentsSection(outDir) {
             `<img src={MagicPixelAssetsById["<asset-uuid>"]} />`,
             '```',
             '',
-            'When you rename or move an asset, `magicpixel sync` prints both the old → new key',
+            `When you rename or move an asset, \`${cmd('sync')}\` prints both the old → new key`,
             'and the matching `MagicPixelAssetsById[...]` hint so you can pick whichever you prefer.',
         ];
     return [

package/dist/util/invoke.js

@@ -0,0 +1,47 @@
+/**
+ * How should we tell the user to run a subcommand?
+ *
+ * `magicpixel` is only the BIN name; the published package is
+ * `@magicpixelart/cli`. So npx-ing the bin name directly (e.g. `magicpixel init` via npx) 404s in a
+ * project with no local install ("'magicpixel@*' is not in this registry"), which is a dead end
+ * for anyone driving the CLI purely through `npx @magicpixelart/cli …`.
+ *
+ * Rule: if the package resolves from the project's node_modules, the bin is on
+ * the PATH for `npx`/scripts and the short `magicpixel <cmd>` form works.
+ * Otherwise we print the always-correct `npx @magicpixelart/cli <cmd>` form.
+ * When in doubt we prefer the long form — it works in both worlds.
+ */
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+export const PKG_NAME = '@magicpixelart/cli';
+let cachedLocal = null;
+/** True when `@magicpixelart/cli` is installed in the current project. */
+export function hasLocalInstall(cwd = process.cwd()) {
+    if (cachedLocal !== null)
+        return cachedLocal;
+    let local = false;
+    try {
+        // Resolve as if requiring from <cwd>/index.js so only the project's
+        // node_modules chain counts — not the npx cache this process runs from.
+        const req = createRequire(resolve(cwd, 'index.js'));
+        req.resolve(`${PKG_NAME}/package.json`);
+        local = true;
+    }
+    catch {
+        local = false;
+    }
+    cachedLocal = local;
+    return local;
+}
+/** Reset the memoized probe (tests only). */
+export function resetInvokeCache() {
+    cachedLocal = null;
+}
+/**
+ * Format a runnable command hint, e.g. `cmd('login')` →
+ * "npx @magicpixelart/cli login" or "magicpixel login".
+ */
+export function cmd(subcommand, cwd) {
+    const suffix = subcommand ? ` ${subcommand}` : '';
+    return hasLocalInstall(cwd) ? `magicpixel${suffix}` : `npx ${PKG_NAME}${suffix}`;
+}

package/dist/util/prunePolicy.js

@@ -0,0 +1,33 @@
+/**
+ * Which local PNGs a full sync is allowed to delete.
+ *
+ * Pruning used to be "anything on disk the manifest didn't mention". Two-way
+ * Unity sync breaks that assumption in two directions:
+ *
+ *   - Strict Unity opt-in excludes entries whose `unity` flag the server
+ *     omitted (older edge deploy, work-budget-starved manifest backfill). Those
+ *     are "unknown", not "unwanted" — deleting their sprite because of a
+ *     transient server response would be data loss inside someone's game
+ *     project. They're protected instead.
+ *   - Sprites authored in Unity have no manifest entry until `magicpixel push`
+ *     adopts them. They're pending, not orphaned.
+ *
+ * Everything we HAVE synced before (it's in `state.synced`) and that the
+ * manifest no longer references is a genuine orphan and still prunes: renames,
+ * deletions, and un-checked "Sync to Unity" boxes all keep working.
+ */
+export function selectFullSyncOrphans({ localPaths, remoteDiskPaths, protectedPaths, isTracked, }) {
+    const orphans = [];
+    const pendingPush = [];
+    for (const p of localPaths) {
+        if (remoteDiskPaths.has(p))
+            continue;
+        if (protectedPaths?.has(p))
+            continue;
+        if (isTracked(p))
+            orphans.push(p);
+        else
+            pendingPush.push(p);
+    }
+    return { orphans, pendingPush };
+}

package/dist/util/pushPlan.js

@@ -0,0 +1,74 @@
+/**
+ * Plan a disk → MagicPixel push.
+ *
+ * Pure so the decision table (skip / update / adopt / needs-flatten) is unit
+ * testable without touching the network or the filesystem.
+ *
+ * Two shapes reach the server:
+ *   - UPDATE: the key is in the sync state, so we know the exact artboard and
+ *     the composite sha we last wrote. A changed disk sha means a local edit.
+ *   - ADOPT:  the key is new on disk (a sprite someone created in Unity), so
+ *     the server mirrors the folders into the library and appends/creates the
+ *     document.
+ */
+/**
+ * Slug rule mirrored from the server (`slugify` + `SEGMENT_RE` in
+ * `src/lib/integration/artboardComposite.server.ts`). The server is the
+ * authority; this copy only exists so the CLI can pre-validate a path before
+ * spending a request, and `pushPlan.test.ts` pins the two together.
+ */
+export function pushSlug(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64)
+        .replace(/-+$/g, '');
+}
+export const MAX_PUSH_PATH_SEGMENTS = 8;
+export function planPush(candidates, synced, opts = {}) {
+    const state = synced ?? {};
+    const out = [];
+    for (const c of candidates) {
+        const known = state[c.key];
+        if (known) {
+            if (known.sha256 === c.diskSha256) {
+                out.push({ kind: 'skip', key: c.key, reason: 'unchanged' });
+                continue;
+            }
+            // Legacy row: the cloud has no addressable artboard, and adopting would
+            // duplicate art that already exists in the library.
+            if (known.legacy) {
+                out.push({ kind: 'skip', key: c.key, reason: 'legacy' });
+                continue;
+            }
+            if (!opts.flatten && typeof known.layers === 'number' && known.layers > 1) {
+                out.push({ kind: 'needs-flatten', key: c.key, layers: known.layers });
+                continue;
+            }
+            out.push({
+                kind: 'update',
+                key: c.key,
+                assetId: known.assetId,
+                layerIdx: known.layerIdx,
+                baseSha256: known.sha256,
+            });
+            continue;
+        }
+        // New on disk → adopt. Needs at least a document + artboard segment.
+        const pathNames = c.segments.slice(-MAX_PUSH_PATH_SEGMENTS);
+        const path = pathNames.map(pushSlug);
+        if (path.length < 2 || path.some((s) => !s)) {
+            out.push({ kind: 'skip', key: c.key, reason: 'unusable-path' });
+            continue;
+        }
+        out.push({
+            kind: 'adopt',
+            key: c.key,
+            path,
+            pathNames,
+            name: pathNames[pathNames.length - 1],
+        });
+    }
+    return out;
+}

package/dist/util/unityFilter.js

@@ -0,0 +1,25 @@
+/**
+ * Per-artboard Unity sync opt-in (strict).
+ *
+ * In the editor, each artboard has a "Sync to Unity" checkbox (and library
+ * folders have a folder-level switch that cascades). A project may hold 100
+ * drafts but only 3 artboards that belong in the Unity project, so the CLI
+ * mirrors the in-app sync button and pulls ONLY the flagged ones.
+ *
+ * Strict opt-in: `unity === true` syncs, anything else does not. A missing
+ * flag means the server didn't say (older edge deploy, or a budget-starved
+ * manifest backfill) — those entries are excluded and reported via
+ * `unknownFlags` so the caller can warn instead of silently syncing the whole
+ * library into someone's game project.
+ */
+export function filterUnityManifest(manifest, opts = {}) {
+    if (opts.syncAll)
+        return { entries: manifest, noneFlagged: false, unknown: [] };
+    const entries = manifest.filter((e) => e.unity === true);
+    const unknown = manifest.filter((e) => typeof e.unity !== 'boolean');
+    return {
+        entries,
+        noneFlagged: manifest.length > 0 && entries.length === 0,
+        unknown,
+    };
+}

package/dist/util/unityMeta.js

@@ -0,0 +1,162 @@
+/**
+ * Unity `.meta` generation for CLI-synced sprites.
+ *
+ * MIRROR: the TextureImporter body below is byte-identical to the in-app
+ * engine's (`src/utils/unitySync/unityMeta.ts`) so both sync paths produce the
+ * same pixel-art-correct importer settings. A sync test
+ * (`src/utils/unitySync/__tests__/unityMetaMirror.test.ts`) fails if they
+ * drift. The duplication is deliberate: the CLI is published as a standalone
+ * npm package and cannot import from the web app's source tree.
+ *
+ * GUIDs are derived deterministically from the asset identity, so re-running
+ * sync never changes a sprite's GUID and Unity scene/prefab references survive.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+export const DEFAULT_UNITY_PPU = 32;
+/** 32-char hex GUID, stable for a given seed. */
+export function unityGuid(seed) {
+    return createHash('sha256').update(seed).digest('hex').slice(0, 32);
+}
+/**
+ * TextureImporter meta tuned for pixel art:
+ * - textureType 8 (Sprite), single sprite mode
+ * - filterMode 0 (Point — no filtering)
+ * - textureCompression 0 (none)
+ * - mipmaps off, nPOTScale 0 (keep original size), wrap clamp
+ * - alphaIsTransparency 1
+ */
+export function buildTextureImporterMeta(guid, ppu) {
+    return `fileFormatVersion: 2
+guid: ${guid}
+TextureImporter:
+  internalIDToNameTable: []
+  externalObjects: {}
+  serializedVersion: 12
+  mipmaps:
+    mipMapMode: 0
+    enableMipMap: 0
+    sRGBTexture: 1
+    linearTexture: 0
+    fadeOut: 0
+    borderMipMap: 0
+    mipMapsPreserveCoverage: 0
+    alphaTestReferenceValue: 0.5
+    mipMapFadeDistanceStart: 1
+    mipMapFadeDistanceEnd: 3
+  bumpmap:
+    convertToNormalMap: 0
+    externalNormalMap: 0
+    heightScale: 0.25
+    normalMapFilter: 0
+    flipGreenChannel: 0
+  isReadable: 0
+  streamingMipmaps: 0
+  streamingMipmapsPriority: 0
+  vTOnly: 0
+  ignoreMipmapLimit: 0
+  grayScaleToAlpha: 0
+  generateCubemap: 6
+  cubemapConvolution: 0
+  seamlessCubemap: 0
+  textureFormat: 1
+  maxTextureSize: 2048
+  textureSettings:
+    serializedVersion: 2
+    filterMode: 0
+    aniso: 1
+    mipBias: 0
+    wrapU: 1
+    wrapV: 1
+    wrapW: 1
+  nPOTScale: 0
+  lightmap: 0
+  compressionQuality: 50
+  spriteMode: 1
+  spriteExtrude: 1
+  spriteMeshType: 1
+  alignment: 0
+  spritePivot: {x: 0.5, y: 0.5}
+  spritePixelsToUnits: ${ppu}
+  spriteBorder: {x: 0, y: 0, z: 0, w: 0}
+  spriteGenerateFallbackPhysicsShape: 1
+  alphaUsage: 1
+  alphaIsTransparency: 1
+  spriteTessellationDetail: -1
+  textureType: 8
+  textureShape: 1
+  singleChannelComponent: 0
+  flipbookRows: 1
+  flipbookColumns: 1
+  maxTextureSizeSet: 0
+  compressionQualitySet: 0
+  textureFormatSet: 0
+  ignorePngGamma: 0
+  applyGammaDecoding: 0
+  swizzle: 50462976
+  cookieLightType: 0
+  platformSettings:
+  - serializedVersion: 4
+    buildTarget: DefaultTexturePlatform
+    maxTextureSize: 16384
+    resizeAlgorithm: 0
+    textureFormat: -1
+    textureCompression: 0
+    compressionQuality: 50
+    crunchedCompression: 0
+    allowsAlphaSplitting: 0
+    overridden: 0
+    ignorePlatformSupport: 0
+    androidETC2FallbackOverride: 0
+    forceMaximumCompressionQuality_BC6H_BC7: 0
+  spriteSheet:
+    serializedVersion: 2
+    sprites: []
+    outline: []
+    customData:
+    physicsShape: []
+    bones: []
+    spriteID:
+    internalID: 0
+    vertices: []
+    indices:
+    edges: []
+    weights: []
+    secondaryTextures: []
+    spriteCustomMetadata:
+      entries: []
+    nameFileIdTable: {}
+  mipmapLimitGroupName:
+  pSDRemoveMatte: 0
+  userData:
+  assetBundleName:
+  assetBundleVariant:
+`;
+}
+/**
+ * Write `<file>.png.meta` beside each synced PNG that doesn't have one yet.
+ *
+ * Existing `.meta` files are never overwritten: once Unity has imported a
+ * sprite the user may have tweaked its importer settings (pivot, slicing,
+ * PPU) and clobbering that on every sync would be hostile. Delete the `.meta`
+ * to regenerate it.
+ */
+export async function writeMissingUnityMetas(sprites, ppu = DEFAULT_UNITY_PPU) {
+    const result = { written: 0, failed: 0 };
+    for (const sprite of sprites) {
+        const metaPath = `${sprite.pngPath}.meta`;
+        if (!existsSync(sprite.pngPath) || existsSync(metaPath))
+            continue;
+        try {
+            await writeFile(metaPath, buildTextureImporterMeta(unityGuid(sprite.id), ppu));
+            result.written++;
+        }
+        catch {
+            // Non-fatal: Unity generates its own default .meta on import. Counted
+            // so `sync` can surface a single warning line instead of failing.
+            result.failed++;
+        }
+    }
+    return result;
+}

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {
     "magicpixel": "dist/index.js"
   },
-  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",