docs: design manual recent furni resync

docs/superpowers/specs/2026-08-02-manual-recent-furni-resync-design.md

@@ -0,0 +1,70 @@
+# Manual Recent Furni Resync Design
+
+## Goal
+
+Add a safe manual command to the existing Admin Import Furni screen for
+refreshing furniture imported during the last seven days. The command must
+update the live FurnitureData metadata and emulator caches without deleting
+database rows or regenerating existing asset bundles.
+
+## User interface
+
+Add `Update imported furni` to the existing `Tools` dropdown on
+`/admin/import/furni`.
+
+Selecting it opens a confirmation dialog that states the fixed scope: furniture
+recorded by the admin audit log as imported during the last seven days. While
+the operation is running, the action and confirmation button are disabled and a
+loading state is shown to prevent duplicate requests.
+
+After completion, show a result panel containing:
+
+- examined item count;
+- successfully resynced item count;
+- failed item count;
+- emulator RCON refresh status;
+- returned per-item errors, when present.
+
+## Data flow
+
+The client sends an authenticated, CSRF-protected `POST` request through
+`adminFetch` to the existing endpoint:
+
+`/api/admin/import/furni/resync?days=7`
+
+The endpoint remains authoritative for selecting the targets. It reads only
+`ItemsBase` IDs referenced by `admin_audit_log` entries whose action is
+`furni_import`, target is `ItemsBase`, and timestamp falls within the last seven
+days.
+
+For each target, the existing resync logic rebuilds its FurnitureData entry,
+enriches it from the configured `habbo_gamedata_hotel`, and upserts it into the
+live `FurnitureData.json`. It then requests `updateCatalog` and `updateItems`
+through RCON.
+
+## Safety and permissions
+
+- Reuse the endpoint's `ASSETS_IMPORT` permission check and admin CSRF guard.
+- Do not expose a UI option for `all=1`.
+- Do not delete or recreate `items_base` or catalog rows.
+- Do not regenerate `.nitro`, SWF, or icon files.
+- Keep returned errors visible without treating an RCON failure as a successful
+  refresh.
+
+## Error handling
+
+Network or non-JSON failures produce an error toast and leave the command
+available for retry. A successful API response is rendered even when individual
+items failed, so the administrator can distinguish partial completion from a
+request failure.
+
+The result panel is dismissible. Running the command again replaces the prior
+result.
+
+## Verification
+
+- Unit-test the result normalization used by the UI, including partial failures
+  and RCON status.
+- Verify that the client calls exactly `resync?days=7` through `adminFetch`.
+- Run focused tests, Biome, TypeScript, the full test suite, and a production
+  build.