Primary shared cache file UX improvements

docs/guide/sharedcache.md

@@ -53,11 +53,30 @@ To load the shared cache, open the **Primary** file in Binary Ninja. In the exam
 ???+ Danger "Warning"
     Opening any other file (e.g. `dyld_shared_cache_arm64.01`) will result in a partial shared cache, with only the information present in the file you opened.
 
+### Original Cache Files Are Required
+
+Unlike other binaries, when you save an analysis database (`.bndb`) for the shared cache, Binary Ninja will not include the original files in the database. As a result, reopening the database still requires access to the `dyld_shared_cache` file and any related cache files in the same set.
+
+This is required even if you previously loaded only a small number of images because Binary Ninja re-parses the shared cache headers on load and analysis may need information from images that were not previously loaded into the view. For example, names for external symbols can be defined by other images in the cache, so metadata from other files than the images you explicitly loaded may be needed.
+
+If Binary Ninja cannot find the primary shared cache file when reopening a database, it may ask you to select it. Select the original primary `dyld_shared_cache` file, not another `.bndb` database.
+
+When running without the UI, Binary Ninja will try and resolve the primary file automatically (or use `loader.dsc.primaryFilePath`, if provided). If the provided path is invalid or missing, and the primary shared cache file can't be found automatically, the database won't load. An example of specifying the location manually is:
+
+```python
+from binaryninja import load
+
+bv = load(
+    "your_database.bndb",
+    options={"loader.dsc.primaryFilePath": "/path/to/dyld_shared_cache_arm64"},
+)
+```
+
+Note: `loader.dsc.primaryFilePath` is used only for the *current* load. Binary Ninja does not persist the absolute override path. When the primary file is resolved in a project, Binary Ninja stores the project-relative path. When it is resolved outside a project, Binary Ninja stores a path relative to the database when possible.
+
 ### Project Support
 
-Binary Ninja projects support `dyld_shared_cache` files. However, due to the nature of the project files not having a mappable path,
-saving the analysis database (`.bndb`) in a separate directory will require you to select the primary shared cache file on
-every open of the database. As a result, we advise keeping your analysis database in the same folder as your `dyld_shared_cache` files.
+Binary Ninja projects support `dyld_shared_cache` files. We recommend keeping your analysis database (`.bndb`) in the same project folder as your `dyld_shared_cache` files. If the database and shared cache files are in different project folders, Binary Ninja will try to store and resolve the primary shared cache file using its project-relative path.
 
   - `your_project_folder`
     - `dyld_shared_cache_arm64` (**Primary**)
@@ -66,6 +85,7 @@ every open of the database. As a result, we advise keeping your analysis databas
     - `dyld_shared_cache_arm64.symbols` (Symbols, optional)
     - `your_database.bndb` (This is recommended)
 
+
 ## Interacting With a Shared Cache
 
 After opening a `dyld_shared_cache`, you will be provided a supercharged binary view: one which has information not only from