docs: document source subtree layout rules

AI.md

@@ -1279,4 +1279,25 @@ Next patch number should be `0253`.
   instead keep shared parser/handler branches shared and place the appropriate
   `Request:`/`Response:` notes next to the relevant case labels.
 
-Next patch number should be `0261`.
+## 2026-06-02 - Patch 0261 source/header subtree layout rules
+
+- Documented the planned large-source-file split as a module-subtree layout,
+  not a semantic provider change.  Source files should move under
+  `src/<module>/` while headers mirror the same hierarchy under
+  `include/<module>/`.
+- Keep ownership names explicit: `nwconn` code stays under `src/nwconn/`,
+  `nwbind` code under `src/nwbind/`, `nwqueue` code under `src/nwqueue/`,
+  `nwnds` code under `src/nwnds/`, and directory code under
+  `src/nwdirectory/`.
+- Flat headers remain umbrella headers.  For example, `include/nwbind.h` should
+  include public headers from `include/nwbind/*.h`; do the same later for
+  `nwconn.h`, `nwqueue.h`, `nwnds.h`, and `nwdirectory.h`.
+- Private implementation headers should be named `include/<module>/internal.h`
+  and may only be included by files in the matching `src/<module>/` subtree.
+- Mechanical move/split patches must not change runtime behavior and must not be
+  combined with endpoint semantics, provider IPC changes, or switch cleanup.
+- Start with build-system support for `src/<module>/*.c` plus
+  `include/<module>/*.h`, then move smaller modules such as `nwdirectory` before
+  splitting very large files such as `nwconn.c` and `nwbind.c`.
+
+Next patch number should be `0262`.

REDESIGN.md

@@ -729,6 +729,111 @@ part is that future code should avoid making `nwbind` a catch-all sink for
 unrelated NCPs just because it already has an IPC path.
 
 
+## Source and header subtree layout
+
+Large-file cleanup should preserve the same logical ownership names used by the
+provider design.  Split large modules into matching source and header subtrees
+instead of creating unrelated flat files:
+
+```text
+src/
+  nwconn/
+    nwconn.c
+    broadcast.c
+    sync.c
+    files.c
+    serverinfo.c
+    timesync.c
+    rpc.c
+    extension.c
+
+  nwbind/
+    nwbind.c
+    objects.c
+    properties.c
+    sets.c
+    auth.c
+    monitor.c
+
+  nwqueue/
+    nwqueue.c
+    jobs.c
+    print.c
+
+  nwnds/
+    nwnds.c
+    objects.c
+    schema.c
+
+  nwdirectory/
+    nwdirectory.c
+    path.c
+    namespace.c
+    volume.c
+    trustees.c
+
+include/
+  nwconn/
+    nwconn.h
+    broadcast.h
+    sync.h
+    files.h
+    serverinfo.h
+    timesync.h
+    rpc.h
+    extension.h
+    internal.h
+
+  nwbind/
+    nwbind.h
+    objects.h
+    properties.h
+    sets.h
+    auth.h
+    monitor.h
+    internal.h
+
+  nwqueue/
+    nwqueue.h
+    jobs.h
+    print.h
+    internal.h
+
+  nwnds/
+    nwnds.h
+    objects.h
+    schema.h
+    internal.h
+
+  nwdirectory/
+    nwdirectory.h
+    path.h
+    namespace.h
+    volume.h
+    trustees.h
+    internal.h
+```
+
+The old flat module headers remain as compatibility and convenience umbrella
+headers.  For example, `include/nwbind.h` should include the public headers
+under `include/nwbind/*.h`; callers that need all public bindery declarations
+can keep including `nwbind.h`, while split implementation files may include
+narrower headers such as `nwbind/monitor.h` or `nwbind/properties.h`.  Use the
+same umbrella pattern for `nwconn.h`, `nwqueue.h`, `nwnds.h`, and
+`nwdirectory.h` as those modules move.
+
+`include/<module>/internal.h` is a private module header.  It may only be
+included by files in the matching `src/<module>/` subtree.  If another module
+needs a declaration, that declaration belongs in an explicit public header under
+`include/<module>/` and can be re-exported by the flat umbrella header.
+
+This layout is compatible with the later provider split, but it is not the same
+thing as a process split.  A mechanical move from `src/nwconn.c` to
+`src/nwconn/sync.c`, or from `src/nwbind.c` to `src/nwbind/monitor.c`, must not
+change runtime behavior.  Build-list changes and include-path changes belong in
+the same mechanical move patch; endpoint semantics, provider IPC, and switch
+cleanup belong in later semantic patches.
+
 ## Provider boundary versus process boundary
 
 A provider boundary is not the same thing as a Unix process boundary.  This is

TODO.md

@@ -173,6 +173,32 @@ Current status:
   follow-up.  For example, SDK group `0x2222/23` is the top-level wire
   `case 0x17`; SDK group `0x2222/123` is top-level wire `case 0x7b`.
 
+
+#### Source/header subtree layout migration
+
+Current status:
+
+- Patch `0261` documents the target source/header subtree layout in `AI.md` and
+  `REDESIGN.md`.  Large modules should move into `src/<module>/` and their
+  headers should mirror that under `include/<module>/`.
+- Flat headers such as `include/nwbind.h` remain umbrella headers that include
+  the public headers from `include/nwbind/*.h`; the same pattern should be used
+  for `nwconn.h`, `nwqueue.h`, `nwnds.h`, and `nwdirectory.h`.
+- Private module headers use `include/<module>/internal.h` and may only be
+  included by files in the matching `src/<module>/` subtree.
+- This is a mechanical layout rule only.  Move/split patches must not change
+  runtime behavior, endpoint semantics, provider IPC, or active switch/fall-
+  through structure.
+
+Follow-up:
+
+- Add build-system support for `src/<module>/*.c` and module-qualified include
+  paths.
+- Move `nwdirectory` into `src/nwdirectory/` and `include/nwdirectory/` first as
+  a smaller layout proof.
+- Then move `nwconn`, `nwbind`, `nwqueue`, and `nwnds` shells into matching
+  subtrees before splitting their large files by topic.
+
 Endpoint coverage index:
 
 - SDK `0x2222/23` / wire `0x17` File Server Environment: the audit has covered