Work on debian packaging.

INDEX.md

@@ -12,11 +12,11 @@ The submodules are:
 
 - [grid](./grid/README.md)
 - [sdl](./sdl/README.md)
-- [dimgui](./dimgui/README.md)
-- [dimgui-sdl](./dimgui-sdl/README.md)
+- [is3r](./is3r/README.md)
 
 ## Building
 
+
 The unifying build system for all submodules is CMake and this can be configured to build all submodules at once.
 
 To build the entire project, simply run the following commands in the root of the repository:
@@ -40,4 +40,43 @@ These control the default state of submodules so enabling them will enable them
 
 `HDK_COVERAGE_FAIL_UNDER` is a percentage threshold for code coverage that will cause the build to fail if not met.
 
+## Dependency and Asset Resolution Policy
+
+HDK subprojects now follow the same resolution strategy for examples and most third-party dependencies:
+
+1. Attempt to use an installed system package with a minimum required version.
+2. If no suitable package is found, fall back to `FetchContent`.
+
+For shared example assets this means examples try to use `hdk-assets` first, then fetch from:
+
+- `https://git.ufp.institute/ufp/hdk-assets.git`
+
+The default minimum shared assets version is:
+
+- `v0.0.1`
+
+Top-level knobs:
+
+- `HDK_USE_SYSTEM_DEPS`
+- `HDK_ASSETS_MIN_VERSION`
+- `HDK_ASSETS_GIT_REPOSITORY`
+
+## Install Layout
+
+HDK uses standard GNU install variables and keeps all package outputs under one install prefix.
+By default, shared example assets install to `${CMAKE_INSTALL_PREFIX}/assets`.
+
+Typical install tree under a custom prefix like `/opt/hdk`:
+
+| Path | Purpose |
+| --- | --- |
+| `/opt/hdk/bin` | Executables and installed examples |
+| `/opt/hdk/lib` | Libraries and CMake package files |
+| `/opt/hdk/include` | Public headers |
+| `/opt/hdk/assets` | Shared example assets |
+
+Asset install subdirectory can be overridden with:
+
+- `HDK_INSTALL_ASSETSDIR`
+