docs: fully document platform mixin dirs and prestage checks

Add directory layout, tooling table, and sync-file-deps recursive scan
for mixins/** in PLATFORM_MIXINS, MODULES, RELEASE, and ARCHITECTURE.
Extend doc drift smoke to require prestage documentation strings.

Co-authored-by: Cursor <[email protected]>

ARCHITECTURE.md

@@ -222,7 +222,7 @@ Edits, deletes, reactions, pins, and thread creates follow the same pattern with
 
 ## Platform facade (Phase 756+)
 
-`PearcordPlatform` is a **mixin-composed** facade: **76** runtime `platform-*` mixins plus **136** manifest assignment rows (`platform-mixin-assign-manifest.js`, `platform-runtime-mixin-registry.js`). The class shell is ~900 lines; behavior is split by domain (view/build, guild sync ingest, search, partition heal, JSON export surface, permissions). Full map: [PLATFORM_MIXINS.md](./PLATFORM_MIXINS.md).
+`PearcordPlatform` is a **mixin-composed** facade: **76** runtime `platform-*` mixins plus **136** manifest assignment rows (`platform-mixin-assign-manifest.js`, `platform-runtime-mixin-registry.js`). Mixin **sources** live under `pearcord-platform/mixins/` (`domain/`, `json-export/`, `runtime/<area>/`); registries and `platform-class-imports.js` stay at package root. The class shell is ~900 lines. Full map: [PLATFORM_MIXINS.md](./PLATFORM_MIXINS.md).
 
 ---
 

MODULES.md

@@ -135,6 +135,20 @@ npm run release
 
 `npm run stage` and `npm run dry-stage` run `prestage` automatically. CI publish (`scripts/ci-pear-publish.sh`) runs the same sync.
 
+### What `prestage` verifies
+
+`scripts/sync-file-deps.cjs` copies each `file:` module into `node_modules` (real directories, not symlinks) and greps for **critical symbols**:
+
+| Package | Patterns checked |
+|---------|------------------|
+| `pearcord-shared` | `USER_UPSERT: 86`, `DM_CHANNEL_UPSERT: 87` |
+| `pearcord-guild` | `gossipUserUpsert` |
+| `pearcord-contacts` | `sendDmChannelInvite` |
+| `pearcord-dm` | `gossipUserUpsert`, `gossipAttachmentMeta` |
+| `pearcord-platform` | `_scheduleProfileGossipBurst`, `sendDmChannelInvite` (recursive scan of **all** `.js`, including `mixins/**`) |
+
+Failure prints `SYNC_FILE_DEPS_CRITICAL_FAIL` — common after moving platform mixins without updating `sync-file-deps` to scan subfolders. Platform layout: [PLATFORM_MIXINS.md](./PLATFORM_MIXINS.md).
+
 Smokes: `npm run test:prestage-sync`, `npm run test:module-exports`, `npm run test:contacts-presence-profile`, `npm run test:open-dm-fallback`.
 
 ---

PLATFORM_MIXINS.md

@@ -16,6 +16,53 @@
 
 Mixins are plain objects merged onto the prototype; they call `this.*` on shared platform state (db, guild, meshes, caches).
 
+## Directory layout (2026-06)
+
+All mixin **source files** live under `modules/pearcord-platform/mixins/` (package root keeps registries, `index.js`, `platform-class-imports.js`, and `platform-*-imports.js` only):
+
+```
+mixins/
+  domain/                 # 16 legacy feature mixins
+  json-export/            # 43 *-json-mixin.js
+  runtime/
+    core/                 # session, hyperswarm, capabilities, diagnostics
+    mesh/                 # guild mesh peers, auto-heal, federation view
+    guild-sync/           # sync watermarks, wire, ingest/export
+    search-discovery/     # search index, discovery, forum
+    partition-heal/       # partition heal slices
+    view/                 # view(), caches, unread audit
+    voice-dm/             # DM session, voice mesh, contacts presence
+    features/             # messaging, permissions, channels, bots, …
+  mixin-paths.json        # basename → folder (tooling)
+  README.md               # folder index (this file)
+```
+
+Manifest `module` paths look like `./mixins/runtime/view/platform-view-mixin`. Assign **order is unchanged** from the flat layout era.
+
+### Relative imports
+
+| File location | `platform-class-imports` | Other package-root modules |
+|---------------|--------------------------|----------------------------|
+| `mixins/domain/*.js`, `mixins/json-export/*.js` | `../../platform-class-imports` | N/A (usually npm packages only) |
+| `mixins/runtime/<area>/*.js` | `../../../platform-class-imports` | `../../../platform-hyperdb-sync`, etc. |
+
+## Tooling (`apps/pearcord/scripts/`)
+
+| Script | Purpose |
+|--------|---------|
+| `generate-mixin-paths-json.py` | Refresh `mixins/mixin-paths.json` from manifest + category rules |
+| `migrate-platform-mixin-dirs.py` | Move files + rewrite manifest paths + fix import depth |
+| `fix-platform-mixin-root-imports.py` | Repair `require('./platform-*')` → `../../../platform-*` under `mixins/` |
+| `regenerate-apply-platform-mixins.py` | Regenerate `apply-platform-mixins.js` (Pear static requires) |
+| `regenerate-runtime-mixin-registry.py` | Regenerate `platform-runtime-mixin-registry.js` (76 runtime rows) |
+| `smoke-platform-mixin-path.cjs` | `mixinFile()` / `resolveMixinFile()` for phase smokes |
+
+App npm script: `npm run regenerate:platform-mixins` (runs both regenerate scripts from `pearcord-platform`).
+
+## OTA / prestage (`sync-file-deps`)
+
+`npm run prestage` rsyncs `file:../../modules/*` into `node_modules` before `pear stage`. Critical checks grep each package for required symbols. For **`pearcord-platform`**, `scripts/sync-file-deps.cjs` recursively reads **all** `.js` under the package (including `mixins/**`) so strings such as `sendDmChannelInvite` and `_scheduleProfileGossipBurst` are found after the directory move. See [MODULES.md](./MODULES.md#ota-staging-file-deps) and [RELEASE.md](./RELEASE.md#prestage-sync-file-deps).
+
 ## Domain groups
 
 | Domain | Example mixins | Feature docs |
@@ -45,8 +92,11 @@ New mixins: add `mixins/runtime/<category>/platform-foo-mixin.js`, append a row
 
 ```bash
 cd apps/pearcord
+npm run test:phase730-mixin-manifest   # every manifest path exists on disk
+npm run regenerate:platform-mixins     # after manifest edits
+npm run test:prestage-sync             # sync-file-deps + critical symbols
 npm run test:ci-phase756               # decomposition regression
-npm run test:ci-phase779   # permissions deep links (uses platform navigateDeepLink)
+npm run test:ci-phase779               # permissions deep links
 ```
 
 ## Related

RELEASE.md

@@ -33,6 +33,14 @@ npm run release      # promote release channel
 npm run seed         # seed the network
 ```
 
+### Prestage (`sync-file-deps`)
+
+`npm run prestage` runs before `stage` / `dry-stage`. It **rsyncs** every `file:../../modules/*` dependency into `apps/pearcord/node_modules` (replacing symlinks so Pear does not follow broken nested trees) and asserts critical API strings still exist in the copied trees.
+
+For **`pearcord-platform`**, checks scan **all** `.js` files under the package, including `mixins/domain/`, `mixins/json-export/`, and `mixins/runtime/**`. Required substrings include `_scheduleProfileGossipBurst` (profile gossip scheduling) and `sendDmChannelInvite` (DM open path via contacts). If prestage fails with `pearcord-platform: missing "sendDmChannelInvite"`, pull latest `pearcord` (`sync-file-deps.cjs` recursive scan) and re-run `npm run prestage`.
+
+Success line: `SYNC_FILE_DEPS_OK`. See [MODULES.md](./MODULES.md#ota-staging-file-deps) and [PLATFORM_MIXINS.md](./PLATFORM_MIXINS.md#ota--prestage-sync-file-deps).
+
 ## Pre-release checklist
 
 - [ ] `npm test` — all smokes + `BOOT_OK` (manual agentctl verification for composer production UI)

scripts/smoke-doc-version-alignment.cjs

@@ -76,6 +76,9 @@ function main () {
   if (!registry.includes("'./mixins/")) {
     throw new Error('platform-runtime-mixin-registry must use ./mixins/ paths')
   }
+  assertIncludes(path.join(DOCS, 'PLATFORM_MIXINS.md'), 'sync-file-deps', 'PLATFORM_MIXINS prestage docs')
+  assertIncludes(path.join(DOCS, 'RELEASE.md'), 'SYNC_FILE_DEPS', 'RELEASE prestage docs')
+  assertIncludes(path.join(DOCS, 'MODULES.md'), 'mixins/**', 'MODULES prestage recursive scan')
 
   console.log(`DOC_VERSION_ALIGNMENT_OK v${ver}`)
 }