fix(tools): importers clear the read-only LFS bit before saving; docs refresh

0.1.3 packaging and setup fixes from what 0.1.x actually exposed.

- New Tools/ue_common.py: make_writable() clears the read-only bit an LFS .umap
  checks out with (save_map() otherwise returns False silently and the staged actor
  is lost) and require_saved() makes that failure visible. ue_hero_facade_import and
  ue_import_north_buildings now call it; the map builders already did. Verified from
  a forced 0o444 map: chmod logged, save_map True, exit 0.
- Docs/build.md: pipeline table now lists the seven site FBXs plus frontage, north,
  hero and map steps and the shared FBX preset; packaging archive corrected to
  Builds/GigLineQA; packaged-log location and -qaselftest usage documented; new
  'Traps that cost real time in 0.1.x' table (read-only save, hero --out is the FBX,
  MPFB add-on path, shot actor quitting under QA, null-RHI trace trap).
- Docs/setup.md: fresh-checkout build marked verified 2026-11-08 and the blocker
  closed; new optional-keys section for OPENROUTER_API_KEY and MAPBOX_ACCESS_TOKEN
  (gitignored .env, not needed by build/tests/release).
- Docs/Architecture 07 + architecture.md: build-output path corrected, marked
  outside the repository.
- 5 new tests for ue_common (54 total).

Tools/README.md

@@ -16,6 +16,7 @@ Geographic tools live in [`Geo/tools/`](../Geo/README.md) and the Blender-side b
 | Tool | Purpose |
 | --- | --- |
 | `check-lfs.sh` | Fails if the `lfs` filter is missing or an LFS-tracked file was committed as a plain blob |
+| `ue_common.py` | Shared helpers for the Unreal commandlet scripts: `make_writable()` clears the read-only bit an LFS `.umap` checks out with (otherwise `save_map()` returns False silently), and `require_saved()` makes that failure explicit. |
 | `fbx_export_preset.py` | The **single** FBX export preset (`ue_metric_v1` / `ue_character_v1`): metres→centimetres via `FBX_SCALE_NONE`, axis mapping east +X / north −Y / up +Z, `mesh_smooth_type="FACE"` (smoothing groups survive the import). Every Blender exporter imports it instead of copying the argument block; `preset_kwargs()` is bpy-free and unit-tested. |
 | `sibling_asset_audit.py` | Reads the sibling project's prop library from GLB headers into `Art/props/reuse-manifest.json`; copies nothing |
 | `scale_test_export.py` / `ue_scale_test_import.py` | The 1 m = 100 uu scale test; the named presets `ue_metric_v1` live in these two files |

Tools/tests/test_ue_common.py

@@ -0,0 +1,70 @@
+"""Tests for Tools/ue_common.py — the shared Unreal commandlet helpers.
+
+Pure stdlib: these helpers exist to turn two silent failures into loud ones, so
+they are tested without starting Unreal.
+"""
+
+import os
+import stat
+import sys
+import tempfile
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+sys.path.insert(0, os.path.join(ROOT, "Tools"))
+
+import ue_common  # noqa: E402
+
+
+class MakeWritableTest(unittest.TestCase):
+    def test_read_only_file_is_made_writable(self):
+        # Exactly how an LFS-tracked .umap checks out: 0o444.
+        with tempfile.NamedTemporaryFile(delete=False) as handle:
+            path = handle.name
+        try:
+            os.chmod(path, 0o444)
+            self.assertFalse(os.access(path, os.W_OK))
+            note = ue_common.make_writable(path)
+            self.assertIsNotNone(note)
+            self.assertIn("chmod u+w", note)
+            self.assertTrue(os.access(path, os.W_OK))
+        finally:
+            os.chmod(path, 0o644)
+            os.unlink(path)
+
+    def test_writable_file_reports_nothing(self):
+        with tempfile.NamedTemporaryFile(delete=False) as handle:
+            path = handle.name
+        try:
+            os.chmod(path, 0o644)
+            self.assertIsNone(ue_common.make_writable(path))
+        finally:
+            os.unlink(path)
+
+    def test_missing_file_raises(self):
+        # A typo must not look like a permissions problem.
+        with tempfile.TemporaryDirectory() as tmp:
+            with self.assertRaises(FileNotFoundError):
+                ue_common.make_writable(os.path.join(tmp, "absent.umap"))
+
+    def test_read_bits_are_preserved(self):
+        with tempfile.NamedTemporaryFile(delete=False) as handle:
+            path = handle.name
+        try:
+            os.chmod(path, 0o400)
+            ue_common.make_writable(path)
+            mode = os.stat(path).st_mode
+            self.assertTrue(mode & stat.S_IRUSR)
+        finally:
+            os.chmod(path, 0o644)
+            os.unlink(path)
+
+
+class RequireSavedTest(unittest.TestCase):
+    def test_passes_the_save_result_through(self):
+        self.assertTrue(ue_common.require_saved(True, "/Game/X"))
+        self.assertFalse(ue_common.require_saved(False, "/Game/X"))
+
+
+if __name__ == "__main__":
+    unittest.main()

Tools/ue_common.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Small shared helpers for the Unreal commandlet scripts.
+
+These run inside `UnrealEditor-Cmd -run=pythonscript`, where a Python `print()`
+is swallowed and a failed save reports `False` rather than raising. Both are traps
+that cost time in `0.1.x`, so they live here once instead of in each script.
+
+    import os, sys
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import ue_common
+
+    ue_common.make_map_writable("/run/media/.../Content/Hollywood/DemoMap.umap")
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+
+
+def is_writable(path: str) -> bool:
+    """True when the current user may write `path` (existing file)."""
+    return os.access(path, os.W_OK)
+
+
+def make_writable(path: str) -> str | None:
+    """Clear read-only bits on `path` so a save cannot fail silently.
+
+    Content is LFS-tracked and `.umap`/`.blend` check out read-only, which makes
+    `EditorLoadingAndSavingUtils.save_map()` return False with no error — the
+    staged actors then vanish on the next load. Returns a note when the mode was
+    changed, `None` when it was already writable, and raises when the file is
+    missing so a typo cannot masquerade as a permissions problem.
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(path)
+    mode = os.stat(path).st_mode
+    if mode & stat.S_IWUSR:
+        return None
+    os.chmod(path, mode | stat.S_IWUSR | stat.S_IRUSR | stat.S_IRGRP | stat.S_IROTH |
+             stat.S_IWGRP)
+    return f"chmod u+w {path} (was {oct(mode & 0o777)})"
+
+
+def require_saved(saved: bool, what: str) -> bool:
+    """Turn a silent `save_map(False)` into a loud failure.
+
+    Use right after a save call: `ue_common.require_saved(saved, LEVEL)`. A
+    commandlet cannot be relied on to exit non-zero, so the caller should log this
+    and make the failure obvious in the result file.
+    """
+    return bool(saved)

Tools/ue_hero_facade_import.py

@@ -12,8 +12,14 @@
 #   centreline, from the street profile), and the hero's east edge at
 #   X = -12024.5 cm (projected control point in local-origin.md).
 
+import os
+import sys
+
 import unreal
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ue_common  # noqa: E402
+
 FBX = "/tmp/gigline/hero-facade.fbx"
 DEST = "/Game/Hollywood/ElCapitan"
 ACTOR_LABEL = "Hero_Facade"
@@ -56,6 +62,19 @@ def import_fbx():
     unreal.EditorLoadingAndSavingUtils.save_dirty_packages(True, True)
 
 
+def _make_map_writable(level: str) -> None:
+    """Clear the read-only bit an LFS .umap checks out with.
+
+    Without this `save_map()` returns False and the staged actor is lost on the
+    next load — no exception, no non-zero exit (see MEMORY: 0.1.x trap).
+    """
+    content = unreal.Paths.project_content_dir()
+    rel = level[len("/Game/"):] if level.startswith("/Game/") else level
+    umap = os.path.join(content, rel + ".umap")
+    note = ue_common.make_writable(umap)
+    if note:
+        log(f"map writable: {note}")
+
 def measure_and_place():
     asset = unreal.EditorAssetLibrary.load_asset(f"{DEST}/SM_HeroFacade")
     if asset is None:
@@ -99,9 +118,12 @@ def measure_and_place():
     comp.set_static_mesh(asset)
     comp.set_mobility(unreal.ComponentMobility.STATIC)
     log(f"placed {ACTOR_LABEL} at {PLACEMENT_CM} (cm) on {LEVEL}")
+    _make_map_writable(LEVEL)
     saved = unreal.EditorLoadingAndSavingUtils.save_map(
         unreal.EditorLevelLibrary.get_editor_world(), LEVEL)
     log(f"save_map {LEVEL}: {saved}")
+    if not ue_common.require_saved(saved, LEVEL):
+        log(f"FAILED to save {LEVEL} — staged content will not persist")
 
 
 try:

Tools/ue_import_north_buildings.py

@@ -15,6 +15,9 @@ import os
 
 import unreal
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ue_common  # noqa: E402
+
 SRC = "/tmp/gigline/north"
 DEST = "/Game/Hollywood/North"
 LEVEL = "/Game/Hollywood/DemoMap"
@@ -72,11 +75,27 @@ def stage():
         mn, mx = box.min, box.max
         log(f"{label}: mesh world-space X {mn.x:.0f}..{mx.x:.0f}  Y {mn.y:.0f}..{mx.y:.0f}  size "
             f"{mx.x-mn.x:.0f}x{mx.y-mn.y:.0f} cm")
+    _make_map_writable(LEVEL)
     saved = unreal.EditorLoadingAndSavingUtils.save_map(
         unreal.EditorLevelLibrary.get_editor_world(), LEVEL)
     log(f"save_map {LEVEL}: {saved}")
+    if not ue_common.require_saved(saved, LEVEL):
+        log(f"FAILED to save {LEVEL} — staged content will not persist")
 
 
+def _make_map_writable(level: str) -> None:
+    """Clear the read-only bit an LFS .umap checks out with.
+
+    Without this `save_map()` returns False and the staged actor is lost on the
+    next load — no exception, no non-zero exit (see MEMORY: 0.1.x trap).
+    """
+    content = unreal.Paths.project_content_dir()
+    rel = level[len("/Game/"):] if level.startswith("/Game/") else level
+    umap = os.path.join(content, rel + ".umap")
+    note = ue_common.make_writable(umap)
+    if note:
+        log(f"map writable: {note}")
+
 def main():
     for fn, asset_name in IMPORTS:
         task = unreal.AssetImportTask()