docs: design production furni asset mapping

docs/superpowers/specs/2026-08-02-production-furni-assets-design.md

@@ -0,0 +1,55 @@
+# Production furni asset destinations
+
+## Problem
+
+The production Nitro client loads furniture icons from `/gamedata/icons`,
+furniture bundles from `/gamedata/bundled/furniture`, and furniture metadata
+from `/gamedata/config/FurnitureData.json`. The importer currently derives its
+mirror paths using the development `Nitro-Files` layout. On the production
+server this creates paths such as `swf/dcr/hof_furni/icons` and
+`nitro-assets/bundled/furniture` below the configured root, which are not the
+directories served by the live client. Manual `.nitro` uploads do not mirror
+assets at all.
+
+Files written only below the CMS `public` directory are also not durable: the
+deployment workflow cleans untracked files from the CMS checkout.
+
+## Design
+
+Keep the existing CMS-local and `Nitro-Files` destinations for compatibility,
+and add the deployed Gamedata tree as a distinct asset layout. In production,
+`/var/www/Gamedata` is detected automatically when it exists. A configurable
+`gamedata_root` setting can override that location for other installations.
+
+The Gamedata layout maps assets as follows:
+
+- icons: `<gamedata_root>/icons`
+- Nitro furniture: `<gamedata_root>/bundled/furniture`
+- FurnitureData: `<gamedata_root>/config/FurnitureData.json`
+- source SWFs: not copied into Gamedata because the Nitro client does not load
+  them; existing CMS-local and `Nitro-Files` SWF handling remains unchanged
+
+Both the normal Habbo importer and manual `.nitro` uploader use the same write
+target resolver. Duplicate destinations are removed before writing.
+
+## Error handling
+
+The CMS-local write remains the primary operation. Every configured or
+auto-detected live destination is treated as an expected mirror. Directory or
+copy failures are returned as import warnings containing the failed target,
+instead of being silently ignored. A successful import therefore cannot hide
+that the live client asset copy failed.
+
+## Compatibility
+
+Existing `nitro_files_root`, `furni_swf_dir`, `furni_icon_dir`,
+`furni_nitro_dir`, and `furni_data_mirror_path` behavior is preserved. The new
+Gamedata destination is additive, so Windows development using the
+`Nitro-Files` layout continues to work.
+
+## Verification
+
+Unit tests will cover Gamedata path derivation, automatic production-root
+detection through an injected root, destination de-duplication, and manual
+upload mirroring. Existing importer tests, type checks, and the production
+build must remain green.