feat(catalog-sync): add import, reconcile, sprite-id and offer steps

The CLI could audit and repair what already existed, but adding furniture
present at a source was still only possible from the admin UI item by item. The
repo already ships every piece of that pipeline, so wire them together as
further steps of the same run:

- `--import-new` imports furniture the compared source has and this hotel lacks.
  It reuses `getClonableClassnames` for the diff and `cloneSingleFurni` per item,
  which downloads the icon and the bundle (sources serve `.nitro`, stored as
  `.hab`), appends the furnidata entry with `deferFurniData` and creates the
  catalog page plus the offer itself. Deferred entries are written in one
  `appendFurniEntriesBulk` call, so 26000 items cost one JSON write, not one per
  item. `--only`, `--limit` and `--concurrency` narrow/tune it, failures are
  isolated per item and never abort the run.
- `--reconcile`, `--fix-sprite-ids` and `--rebuild-offers` run the existing
  `reconcileFurniDataWithItemsBase`, `verifyAndFixSpriteIds` and
  `rebuildCatalogOfferIds` passes — the post-import consistency work.
- `--align-ids` and `--rename-bundles` delegate to the existing standalone
  scripts; both only report until `--apply` is given, matching their own
  contracts.
- The menu grows options 6-8 plus a dry run, each with its own confirmation.

`--everything` turns on every repair + import step but deliberately leaves the
destructive ones off. A live dry run against Wibbo listed 26593 items on the
source that this hotel does not have, and Habbo (COM) reported 2871.

scripts/README.md

@@ -66,13 +66,49 @@ The menu asks which sources to compare (Habbo (COM) is the preset) and what may
 be written. With no arguments it needs a terminal; with any flag it skips the
 menu, so it is usable from cron.
 
+Every step the engine exposes is available as a flag:
+
+| Flag | What it does |
+| :--- | :--- |
+| `--sources=<a,b>` | Compare against these sources (id or display name) |
+| `--icons` | Re-download missing furniture icons |
+| `--nitros` | Re-download missing bundles (stored as `.hab`) |
+| `--furnidata` | Repair `FurnitureData.json` (add missing, drop duplicates) |
+| `--structure` | Repair orphaned / duplicate catalog rows |
+| `--check-ids` | Check `FurnitureData.json` for spriteId conflicts |
+| `--sql` / `--apply-sql` | Generate / apply the catalog SQL |
+| `--organize-sql` | Also emit the `catalog_pages` INSERTs into the SQL file |
+| `--import-new` | Import furniture the source has and this hotel lacks |
+| `--only=<a,b>`, `--limit=N`, `--concurrency=N` | Narrow and tune the import |
+| `--reconcile` | Align `FurnitureData.json` with `items_base` after importing |
+| `--fix-sprite-ids` | Correct `items_base.sprite_id` drift |
+| `--rebuild-offers` | Rebuild catalog `offer_id` mirrors |
+| `--align-ids` | Move `items_base` ids onto their furnidata ids (report; `--apply` runs it) |
+| `--rename-bundles` | Rename legacy `.nitro` bundles to `.hab` (report; `--apply` runs it) |
+| `--everything` | Every repair + import step, but still none of the destructive ones |
+
+`--import-new` is the step that actually adds furniture: `cloneSingleFurni`
+downloads the icon and the bundle (sources serve `.nitro`, the local copy is
+stored as `.hab`), appends the `FurnitureData.json` entry **and** creates the
+catalog page plus the offer, exactly like the app's own import. It skips
+anything already present, so it is safe to re-run.
+
 Safety notes:
 
 - **An audit writes nothing** — no repair flag means read-only.
-- `--apply-sql` is the only flag that changes the catalog, and the generated SQL
-  is always written to `storage/catalog-sync/*.sql` (gitignored) so it can be
-  reviewed or replayed by hand.
+- `--dry-run` together with `--import-new` lists what would be imported and
+  imports nothing; use it first on a source before importing thousands of items.
+- Generating the catalog SQL creates the `catalog_pages` sub-pages it references
+  (same as the app's import), so a "generate only" run is not entirely
+  read-only — only the `catalog_items` rows wait for `--apply-sql`. The SQL also
+  lands in `storage/catalog-sync/*.sql` (gitignored) so it can be reviewed or
+  replayed by hand.
+- `--apply-sql` is the only flag that changes the catalog; `--apply` authorises
+  the two heavyweight child scripts (`align-db-ids`, `migrate-nitro-to-hab`).
+  Both only report without it.
 - The engine is the same one the admin *Catalog audit* page streams
   (`runCatalogAudit`), so a terminal run and an in-admin run agree.
 - `--json` prints one machine-readable report; `--fail-on-errors` exits `3` when
   error-severity issues remain, which is what a scheduled check should use.
+- Items that no compared source can provide stay missing: the run reports them
+  instead of inventing an icon or a bundle.