diff --git a/docs/pnpm/PNPM_MIGRATION.md b/docs/pnpm/PNPM_MIGRATION.md
new file mode 100644
index 00000000..fa0f7dd7
--- /dev/null
+++ b/docs/pnpm/PNPM_MIGRATION.md
@@ -0,0 +1,193 @@
+# PNPM Migration Roadmap
+
+This document is the canonical cross-repo plan for migrating the ByteLyst ecosystem's Node.js/TypeScript repositories from `npm` to `pnpm`.
+
+## Objective
+
+Standardize on `pnpm` for:
+
+- faster installs
+- stricter dependency resolution
+- cleaner workspace behavior with shared `@bytelyst/*` packages
+- consistent CI, Docker, and local development workflows
+
+## Current Status
+
+### Completed Pilot
+
+- **FlowMonk** — completed, audited, verified, and pushed
+  - migration commit: `32160af` — `feat(build): migrate flowmonk to pnpm workspace`
+  - audit fix commit: `c4cb9b3` — `fix(audit): harden push triggers and offline replay`
+  - docs alignment commit: `8894285` — `docs(audit): align flowmonk completion status`
+
+### What the pilot proved
+
+- root workspace migration is workable for multi-surface repos
+- CI must install from the workspace root when shared packages are involved
+- Dockerfiles and helper scripts need explicit `pnpm` handling
+- docs can overstate completion unless a post-migration audit is mandatory
+- post-completion audit must be part of the migration, not an optional cleanup
+
+## Readiness Decision
+
+- **Ready for phased ecosystem rollout:** yes
+- **Ready for one-shot all-at-once migration:** no
+
+Even though none of the repos are actively deployed, the safest quality path is a fast sequential rollout in the right order, not a big-bang cutover.
+
+## Canonical Migration Version
+
+- target package manager metadata: `pnpm@10.6.5`
+
+## Required Quality Gates for Every Repo
+
+Every repo migration must complete **all** of the following before it is marked complete:
+
+### Gate 1 — Manifest and workspace alignment
+
+- add `packageManager: "pnpm@10.6.5"`
+- decide whether the repo needs a root workspace
+- add `pnpm-workspace.yaml` when shared local packages or multi-surface installs require it
+- generate and commit `pnpm-lock.yaml`
+- remove obsolete `package-lock.json` files
+
+### Gate 2 — CI and Docker alignment
+
+- update CI to use `pnpm`
+- update cache configuration to use the right lockfile path(s)
+- update Dockerfiles and helper scripts to install with `pnpm`
+- verify shared package resolution in both local and CI layouts
+
+### Gate 3 — Docs and developer workflow alignment
+
+- update README / AGENTS / CLAUDE / copilot / helper docs
+- update canonical build, test, typecheck, and dev commands
+- update any migration tracker / roadmap docs for the repo
+
+### Gate 4 — Verification
+
+- install succeeds under `pnpm`
+- typecheck passes
+- tests pass
+- build passes
+- any repo-specific required verification is run truthfully
+
+### Gate 5 — Post-completion audit
+
+Required after the migration appears complete:
+
+- review completed claims against actual code and tests
+- identify recently marked-complete features lacking real coverage
+- fix any runtime, ownership, replay, or CI/Docker regressions found
+- rerun verification after the fixes
+- update docs to the audited truth state
+
+## Migration Pattern Proven by FlowMonk
+
+For repos similar to FlowMonk, the proven migration sequence is:
+
+1. add root `package.json` if a workspace root is needed
+2. add `pnpm-workspace.yaml`
+3. generate `pnpm-lock.yaml`
+4. remove old `package-lock.json`
+5. update package-level `packageManager`
+6. update CI
+7. update Dockerfiles and helper scripts
+8. update docs
+9. run full verification
+10. run post-completion audit
+11. commit and push incrementally
+
+## Ecosystem Rollout Order
+
+### Wave 0 — Pilot
+
+- `learning_ai_flowmonk` — complete
+
+### Wave 1 — Best next repos
+
+These are the best next candidates for a high-signal, lower-risk continuation:
+
+- `learning_ai_notes`
+- `learning_ai_local_memory_gpt`
+- `learning_ai_trails`
+
+### Wave 2 — Medium complexity product repos
+
+- `learning_ai_fastgap`
+- `learning_ai_clock`
+- `learning_ai_jarvis_jr`
+- `learning_ai_peakpulse`
+
+### Wave 3 — Higher blast-radius repos
+
+- `learning_voice_ai_agent`
+- `learning_ai_common_plat`
+
+## Why this order
+
+- Wave 1 validates the process across more product repos without immediately touching the largest shared-platform blast radius
+- Wave 2 expands the pattern to broader product surfaces
+- Wave 3 is delayed until the process is stable enough for the biggest dependency and workflow impacts
+
+## Special Notes
+
+### `learning_ai_common_plat`
+
+This repo is already the ecosystem's `pnpm` center of gravity. The work here is less about “switching package manager” and more about:
+
+- standardizing docs/scripts/CI expectations
+- ensuring downstream repos consume shared packages cleanly
+- avoiding regressions in shared package behavior
+
+### `learning_voice_ai_agent`
+
+This repo should keep only a pointer or local wrapper doc once the shared canonical roadmap lives in `learning_ai_common_plat/docs/pnpm/`.
+
+## Minimal Checklist Per Repo
+
+Use this checklist for each migration:
+
+- [ ] package metadata updated
+- [ ] lockfile generated and committed
+- [ ] old npm lockfiles removed
+- [ ] CI updated
+- [ ] Docker/scripts updated
+- [ ] docs updated
+- [ ] install verified
+- [ ] typecheck verified
+- [ ] tests verified
+- [ ] build verified
+- [ ] post-completion audit performed
+- [ ] docs updated to audited truth state
+- [ ] incremental commits pushed
+
+## Operator Guidance
+
+### Do
+
+- migrate repos sequentially in the defined order
+- commit in logical batches
+- push after each verified batch
+- treat the audit as mandatory
+- prefer truthful status over optimistic status
+
+### Do not
+
+- migrate the entire ecosystem in one cutover
+- mark repos complete before the audit pass
+- leave mixed `npm`/`pnpm` docs in a migrated repo
+- assume CI/Docker correctness from local success alone
+
+## Current Recommendation
+
+The next repo to migrate should be:
+
+- **`learning_ai_notes`**
+
+## Summary
+
+- canonical roadmap: `learning_ai_common_plat/docs/pnpm/PNPM_MIGRATION.md`
+- completed pilot: `learning_ai_flowmonk`
+- proven approach: fast sequential waves with mandatory audit
+- next recommended repo: `learning_ai_notes`