docs: document shared library layering plan

REDESIGN.md

@@ -1649,6 +1649,66 @@ not.  The config may point at certificate/key files, while `nwsetup` should be
 able to generate or validate local defaults.  Private keys and provider mTLS
 credentials must live in protected directories with strict permissions.
 
+
+### mars-nwe shared library layering
+
+The MatrixSSL/FLAIM/directory plan should produce mars-nwe-named libraries instead
+of exposing raw upstream library identities to the rest of the project.  This keeps
+linking deterministic, avoids collisions with distro packages, and makes it clear
+which layer owns which compatibility boundary.
+
+Planned library names:
+
+```text
+libnwmatrixssl
+  mars-nwe-maintained MatrixSSL fork/import
+  patched only for CMake, portability, symbol/library naming, and build hygiene
+  provides the low-level GPL-2.0-compatible crypto/TLS implementation
+
+libnwssl
+  mars-nwe SSL/crypto facade
+  provides TLS abstraction for apps/services
+  provides the CCS/NICI compatibility API used by FLAIM encryption paths
+  is the only normal project layer that talks directly to libnwmatrixssl
+
+libnwflaimtk
+  renamed FLAIM FTK support library
+  built from the imported FLAIM source but renamed to avoid system-library
+  conflicts
+
+libnwflaim
+  renamed classic FLAIM database library
+  depends on libnwflaimtk and uses libnwssl only through the CCS/NICI interface
+  when encrypted storage support is enabled
+
+libnwdirectory
+  mars-nwe directory abstraction library
+  provides the C API used by nwdirectory, future nwnds, nwsetup/import tools, and
+  any later Bindery/NDS integration
+  owns the mapping from directory objects/schema/security policy to libnwflaim
+```
+
+The intended dependency direction is:
+
+```text
+LDAP/LDAPS nwdirectory service -> libnwdirectory -> libnwflaim -> libnwflaimtk
+future nwnds/NDS provider      -> libnwdirectory -> libnwflaim -> libnwflaimtk
+nwsetup/import tooling         -> libnwdirectory -> libnwflaim -> libnwflaimtk
+
+libnwflaim encrypted storage   -> libnwssl CCS/NICI compat -> libnwmatrixssl
+service/app TLS                -> libnwssl TLS facade      -> libnwmatrixssl
+```
+
+Consumers must not skip layers for convenience.  `nwdirectory`, future `nwnds`,
+`nwsetup`, `nwbind`, and provider code should call `libnwdirectory` for directory
+state and `libnwssl` for TLS/crypto policy.  They should not include FLAIM,
+MatrixSSL, OpenSSL-style, or CCS/NICI implementation headers directly.
+
+This also means the imported FLAIM targets should not be named exactly like a
+system installation.  Use mars-nwe names such as `NWFlaim::ftk` /
+`NWFlaim::flaim` or equivalent targets that produce `libnwflaimtk` and
+`libnwflaim`, while keeping source-origin notes in `third_party/libflaim`.
+
 ### MatrixSSL fork/CMake rule
 
 `MatrixSSL` should be evaluated as the preferred GPL-2.0-compatible crypto/TLS
@@ -1680,8 +1740,8 @@ Expose normal targets.  The exact names may be adjusted during import, but the
 intended split is:
 
 ```text
-MATRIXSSL::crypto   # crypto primitives used by CCS/NICI compat
-MATRIXSSL::tls      # TLS layer, only if/when mars-nwe needs it
+NWMatrixSSL::crypto   # produces/represents libnwmatrixssl crypto primitives
+NWMatrixSSL::tls      # optional TLS surface from the MatrixSSL fork, if built
 ```
 
 FLAIM should still not include MatrixSSL headers directly.  The intended layering
@@ -1741,7 +1801,7 @@ inside mars-nwe:
 ```
 
 The CMake conversion should separate the library from optional tools/tests,
-expose a normal target such as `FLAIM::flaim`, and support static/shared choices
+expose a normal target such as `NWFlaim::flaim`, and support static/shared choices
 where useful.  The original Makefiles may remain as reference material during the
 import, but they should not be the long-term build path.
 
@@ -1757,8 +1817,8 @@ The first CMake import should be intentionally small and storage-focused:
 
 ```text
 required first targets:
-  FLAIM::ftk      # cross-platform toolkit used by libflaim
-  FLAIM::flaim    # classic FLAIM database library used by libdirectory
+  NWFlaim::ftk    # produces libnwflaimtk, the renamed FTK support library
+  NWFlaim::flaim  # produces libnwflaim, the renamed classic FLAIM DB library
 
 optional later targets:
   FLAIM::sql      # SQL FLAIM, not needed for initial directory store
@@ -1768,7 +1828,8 @@ optional later targets:
   flaim docs      # off by default
 ```
 
-`FLAIM::flaim` depends on the FTK toolkit, so the CMake conversion should model
+`NWFlaim::flaim` depends on the renamed FTK toolkit target, so the CMake
+conversion should model
 that dependency explicitly instead of relying on Autotools' installed-library
 search.  The initial mars-nwe directory-store work only needs the classic FLAIM
 library path; SQL FLAIM, XFLAIM, Java/C# bindings, Doxygen, OBS/debian package
@@ -1788,7 +1849,7 @@ policy.
 If the FLAIM source cannot be built cleanly without old OpenSSL-facing code, the
 preferred fallback is still not to introduce a general OpenSSL/LibreSSL backend
 matrix.  First disable the old FTK TLS-facing code for the required
-`FLAIM::ftk`/`FLAIM::flaim` targets.  If a legacy path is unavoidable, keep the
+`NWFlaim::ftk`/`NWFlaim::flaim` targets.  If a legacy path is unavoidable, keep the
 patch inside `third_party/libflaim` and use a narrow shim or source adjustment;
 do not expose OpenSSL-compatible types outside the FLAIM/FTK build and do not
 make LDAP/provider IPC use OpenSSL APIs.