@bobfrankston/rmfmail 1.0.632 → 1.0.640

package/docs/prod-wrapper.md.merged

@@ -0,0 +1,215 @@
+# prod / dev release workflow — wrapper-package variant
+
+Status: design only. Alternative to `prod.md` (dist-tag approach). Pick one.
+
+## Shape
+
+Today: one package `@bobfrankston/rmfmail` ships everything.
+
+Proposed: split into two packages, three install names.
+
+| Name | Role | Versioning |
+|---|---|---|
+| `@bobfrankston/rmfmailapp` | The actual code (today's rmfmail content). | Bumps freely on every build. |
+| `@bobfrankston/rmfmail` | Thin wrapper. `dependencies: { rmfmailapp: "1.0.NNN" }` pinned. | Bumps only on promotion. |
+| `@bobfrankston/rmfmaildev` | Thin wrapper. `dependencies: { rmfmailapp: "*" }` (or repinned at every publish to current `@latest`). | Tracks rmfmailapp tip. |
+
+Casual user: `npm install -g @bobfrankston/rmfmail` — pulls the wrapper, npm resolves the pinned rmfmailapp, installs both. The wrapper's `bin` shim invokes rmfmailapp's actual entry point.
+
+Dev user: `npm install -g @bobfrankston/rmfmaildev` — wrapper that pulls `rmfmailapp@latest` (or its current `*`-resolved match).
+
+Promotion = single git commit on the wrapper repo bumping its `dependencies.rmfmailapp` from one frozen version to a newer frozen version, plus `npm publish` of the wrapper.
+
+## Why this rather than dist-tags
+
+- **Audit trail in git.** The history of "what version was current prod when" is `git log app/wrapper/package.json`, not registry-only state.
+- **Promotion is reversible by `git revert`.** Same as any code change.
+- **Multi-channel scales.** `rmfmail-beta`, `rmfmail-rc`, etc. are just more wrappers, each pinned independently. dist-tags work too but become a bigger pile.
+- **Pre-flight gating possible.** A CI check on the wrapper's package.json (lint, smoke test) can refuse promotions that name a version that hasn't been validated.
+
+## Why NOT, vs dist-tags
+
+- **Two packages to maintain** instead of one. Two `package.json`s, two `npm publish` calls per promotion.
+- **One more rename.** Current `@bobfrankston/rmfmail` → `@bobfrankston/rmfmailapp` (every workspace dep that references it has to flip too — not many in mailx, but it's a non-trivial rename).
+- **npm cache pressure.** Each version of rmfmailapp lingers in users' npm caches; the wrapper resolves at install time, so old transitive resolutions can sit around. dist-tags don't multiply package versions.
+
+## Layout
+
+```
+mailx/
+  rmfmailapp/                      # was app/, the actual code
+    package.json   → "name": "@bobfrankston/rmfmailapp"
+    bin/mailx.ts   → unchanged
+    packages/      → unchanged
+    client/        → unchanged
+    ...
+
+  rmfmail/                         # NEW — wrapper for prod
+    package.json   → see below
+    bin/rmfmail.js → 3-line shim
+
+  rmfmaildev/                      # NEW — wrapper for dev
+    package.json   → see below
+    bin/rmfmaildev.js → 3-line shim
+```
+
+### `rmfmail/package.json` (prod wrapper)
+
+```json
+{
+  "name": "@bobfrankston/rmfmail",
+  "version": "1.0.0",
+  "description": "Local-first email client (current stable)",
+  "type": "module",
+  "bin": { "rmfmail": "bin/rmfmail.js" },
+  "dependencies": {
+    "@bobfrankston/rmfmailapp": "1.0.609"
+  },
+  "license": "MIT"
+}
+```
+
+Wrapper's own version (`1.0.0`) only bumps on shape changes (e.g., bin renamed, scope changed). Day-to-day promotions just re-pin the dependency line.
+
+### `rmfmail/bin/rmfmail.js` (shim)
+
+```js
+#!/usr/bin/env node
+// Wrapper bin — defer to the pinned rmfmailapp entry point. Keeps argv
+// and exit code identical so the wrapper is invisible at the CLI.
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const appBin = require.resolve("@bobfrankston/rmfmailapp/bin/mailx.js");
+await import(`file://${appBin}`);
+```
+
+(Or even just `require("@bobfrankston/rmfmailapp/bin/mailx.js")` if the rmfmailapp bin runs on `import`.)
+
+### `rmfmaildev/package.json` (dev wrapper)
+
+```json
+{
+  "name": "@bobfrankston/rmfmaildev",
+  "version": "1.0.0",
+  "description": "Local-first email client (development tip)",
+  "type": "module",
+  "bin": { "rmfmail": "bin/rmfmaildev.js" },
+  "dependencies": {
+    "@bobfrankston/rmfmailapp": "*"
+  },
+  "license": "MIT"
+}
+```
+
+`*` means "any version" — npm picks the latest published. New `npm install -g @bobfrankston/rmfmaildev` always installs whatever rmfmailapp tip is at install time. Existing dev users run `npm update -g @bobfrankston/rmfmaildev` to refresh.
+
+Alternative: `rmfmaildev` re-pins on every rmfmailapp publish (`prepublish` hook in rmfmailapp's CI bumps rmfmaildev's pin and publishes). Adds steps but gives dev installs the same lockstep behavior as prod.
+
+### Workflow
+
+**rebuild.cmd** (publishes rmfmailapp):
+```cmd
+cd rmfmailapp
+npmglobalize
+```
+
+No tag flag needed (rmfmailapp's `@latest` is just "newest dev build"; rmfmail prod doesn't read from it directly).
+
+**prod.cmd** (promote):
+```cmd
+@echo off
+setlocal
+set TARGET=%1
+if "%TARGET%"=="" (
+  for /f "tokens=2 delims=:," %%v in ('findstr /b "  \"version\":" "%~dp0rmfmailapp\package.json"') do set TARGET=%%~v
+  set TARGET=%TARGET: =%
+  set TARGET=%TARGET:"=%
+)
+echo Promoting rmfmail wrapper to pin rmfmailapp@%TARGET%...
+
+rem Edit rmfmail/package.json's dependency line. 5-line node one-liner:
+node -e "const p=require('./rmfmail/package.json'); p.dependencies['@bobfrankston/rmfmailapp']='%TARGET%'; require('fs').writeFileSync('./rmfmail/package.json', JSON.stringify(p,null,2)+'\n');"
+
+rem Bump wrapper patch version (so npm sees a new wrapper to install).
+cd rmfmail && npm version patch && cd ..
+git add rmfmail/package.json
+git commit -m "rmfmail: pin rmfmailapp@%TARGET%"
+
+cd rmfmail
+npm publish --access public
+cd ..
+echo Done. Casual users running 'npm install -g @bobfrankston/rmfmail' now get rmfmail@x.y.z → rmfmailapp@%TARGET%.
+endlocal
+```
+
+**Casual install** (unchanged from today's user-facing command):
+```
+npm install -g @bobfrankston/rmfmail
+```
+
+**Dev install**:
+```
+npm install -g @bobfrankston/rmfmaildev
+```
+
+## Required code changes
+
+### 1. Rename `@bobfrankston/rmfmail` → `@bobfrankston/rmfmailapp`
+
+- `app/package.json` `"name"` field.
+- Every `dependencies` reference in workspace `packages/*/package.json`. Today they use `file:` paths so this might already be transparent — check.
+- `bin/postinstall.js` — any hard-coded package name strings.
+- `npmglobalize` config — no changes if it reads from package.json.
+
+The rename is a one-time event. After it lands, no package.json edits in normal day-to-day work.
+
+### 2. Create `rmfmail/` and `rmfmaildev/` directories
+
+Top-level (not under `app/`). Each gets a 5-line `package.json` and a 3-line bin shim. ~30 lines total.
+
+### 3. CI / build wiring
+
+Today's `rebuild.cmd` builds and publishes app. Add:
+- `prod.cmd` — promotes by bumping rmfmail's pin.
+- Optionally automate rmfmaildev re-pin on every app publish (postpublish hook).
+
+### 4. npmglobalize: no changes needed
+
+The wrapper packages publish like any other. dist-tag flag work in `prod.md` is **not required** for this approach.
+
+## What this does NOT do
+
+- Does not enable side-by-side coexistence on a single machine — same as dist-tag plan, that's the orthogonal `RMFMAIL_PROFILE` env-var design.
+- Does not eliminate user upgrades — users still need to re-run `npm install -g` (or rely on mailx's in-app updater) to pick up a new prod pin.
+- Does not split testing or CI per channel — same code, same tests; only the promotion step gates the user-facing pin.
+
+## Comparison to `prod.md`
+
+| | `prod.md` (dist-tag) | `prod-wrapper.md` (this) |
+|--|--|--|
+| Number of npm packages | 1 (rmfmail) | 3 (rmfmailapp + rmfmail + rmfmaildev) |
+| What "promotion" is | `npm dist-tag add` (registry call) | git commit + `npm publish` of wrapper |
+| Promotion auditable in git | no | yes |
+| Roll-back mechanism | retag earlier version | `git revert` then republish wrapper |
+| Required npmglobalize change | yes (`--tag` flag) | no |
+| Casual install command | `npm install -g @bobfrankston/rmfmail` | (same) |
+| Dev install command | `... rmfmail@dev` | `... rmfmaildev` |
+| One-time rename of code package | no | yes (rmfmail → rmfmailapp) |
+| Multi-channel future (beta, rc, …) | more dist-tags | more wrappers |
+
+## Recommendation
+
+If you want:
+- **Minimum mechanical change**: dist-tag (`prod.md`).
+- **Maximum traceability**: wrapper (`prod-wrapper.md`).
+- **Both eventually**: nothing stops doing dist-tag now and migrating to wrapper later. The dist-tag is a cheap throwaway; the wrapper is a structural commitment.
+
+## Effort estimate
+
+- One-time rename `rmfmail` → `rmfmailapp`: ~30 minutes (search-replace + verify, plus npm deprecate of old name to point users at new install path).
+- `rmfmail/` + `rmfmaildev/` skeletons: ~15 minutes.
+- `prod.cmd`: ~15 minutes.
+- Test cycle: build app, publish, run prod.cmd, install in clean dir, verify it runs. ~30 minutes.
+
+About 1.5 hours wall-clock. Bigger one-time investment than dist-tag (~15 minutes); smaller per-promotion friction (one git commit vs `npm dist-tag add ... prod && add ... latest`).

package/docs/prod.md

@@ -1,105 +1,224 @@
 # prod / dev release workflow
 
-Status: design only. Not implemented.
+Status: design. Two viable approaches; pick one. Both deliver the same shape:
 
-## Goal
+- `rebuild.cmd` publishes builds without affecting what casual users get.
+- A separate `prod.cmd` step promotes a known-good build to be what casual users install.
+- Casual users keep typing `npm install -g @bobfrankston/rmfmail` (no flags).
+- Dev users explicitly opt in.
 
-Two flavors of `@bobfrankston/rmfmail` published to the same npm package, distinguished only by [dist-tag](https://docs.npmjs.com/cli/v10/commands/npm-dist-tag):
+## Key invariant (answers the obvious confusion)
 
-- **`@dev`** — every successful `rebuild.cmd` publishes here. Bumps freely; no stability promise.
-- **`@prod`** (and **`@latest`**) — what casual `npm install -g @bobfrankston/rmfmail` gets. Promoted manually from the current `@dev` tip when something has proved stable.
+`@latest` is **what casual `npm install` gets**. It only moves when prod.cmd promotes. So between promotions:
 
-One node_modules root per machine; the active version is whichever the install pulled. No coexistence machinery, no env-var profiles. The simple case stays simple.
+```
+@latest = @prod = 1.0.609   ← last promoted, what users get
+@dev    = 1.0.620           ← every rebuild bumps this
+```
+
+Casual users keep installing 1.0.609 until you say so. Dev tip never accidentally becomes the casual install.
+
+---
+
+## Approach A — npm dist-tags (one package)
+
+### Mechanics
+
+npm's built-in [dist-tag](https://docs.npmjs.com/cli/v10/commands/npm-dist-tag) feature: one package, multiple movable pointers.
 
-## Mechanics
+- `npm publish --tag dev` sets `@dev` to the new version. `@latest` untouched.
+- `npm dist-tag add @bobfrankston/rmfmail@<v> prod` moves the `prod` pointer; `npm dist-tag add ... latest` moves `latest` too. Two HTTP calls, no republish.
 
-npm publishes default to `--tag latest`. Passing `--tag <name>` sets that tag on the new version and **leaves `latest` untouched**. dist-tags are pointers — moving one is two HTTP calls, no republish.
+### Required changes
 
+**1. npmglobalize** — accepts a `--dist-tag` flag and forwards to `npm publish`. ~5 lines. See `docs/npmglobalize-disttag.md` for the patch.
+
+**2. rebuild.cmd** — invoke `npmglobalize --dist-tag dev`. One-line edit.
+
+**3. prod.cmd** — new file. Explicit arg wins; otherwise query npm for the
+current `@dev` and promote that. (`@dev` is the right default because you've
+just published it via `rebuild.cmd` and want it to become user-facing.)
+
+```cmd
+@echo off
+setlocal
+set V=%1
+if "%V%"=="" (
+  for /f "delims=" %%v in ('npm view @bobfrankston/rmfmail dist-tags.dev') do set V=%%v
+)
+if "%V%"=="" (
+  echo No version supplied and 'npm view ... dist-tags.dev' returned empty.
+  echo Usage: prod.cmd [version]   e.g. prod.cmd 1.0.611
+  exit /b 1
+)
+echo Promoting @bobfrankston/rmfmail@%V% to prod and latest...
+call npm dist-tag add @bobfrankston/rmfmail@%V% prod
+call npm dist-tag add @bobfrankston/rmfmail@%V% latest
+echo Done.
+endlocal
 ```
-# what rebuild.cmd should run (via npmglobalize):
-npm publish <tarball> --tag dev          # version exists, dev → it, latest unchanged
 
-# what prod.cmd should run:
-npm dist-tag add @bobfrankston/rmfmail@<version> prod
-npm dist-tag add @bobfrankston/rmfmail@<version> latest
+Roll back to an older known-good: `prod.cmd 1.0.598` — explicit arg path.
+
+The "default = local package.json" alternative (if you never want to query
+the registry):
+
+```cmd
+for /f "tokens=2 delims=:," %%v in ('findstr /b "  \"version\":" "%~dp0app\package.json"') do set V=%%~v
+set V=%V: =%
+set V=%V:"=%
 ```
 
-Anyone running `npm install -g @bobfrankston/rmfmail` keeps installing whatever `latest` currently points at — i.e., the most recent prod-promoted build. Dev users explicitly run `npm install -g @bobfrankston/rmfmail@dev` (one time; subsequent installs stay on dev tip until the user reinstalls).
+Use whichever default matches your workflow — the explicit-arg path works
+either way.
 
-## Required changes
+### Workflow
 
-### 1. npmglobalize (small flag plumbing)
+1. Edit code, run `rebuild.cmd` — version bumps, publishes as `@dev`. `@latest`/`@prod` unaffected.
+2. On the dev machine: `npm install -g @bobfrankston/rmfmail@dev` to grab the freshest build.
+3. When something feels stable: run `prod.cmd`. Promotes the current `package.json` version to `@prod` and `@latest`.
+4. On the prod machine (and any default install): `npm install -g @bobfrankston/rmfmail` (no tag) gets the newly-promoted version.
 
-`/c/users/bob/onedrive/xfer/bin/linuxbin/node_modules/@bobfrankston/npmglobalize/lib.js:4486`:
+Roll back: `npm dist-tag add @bobfrankston/rmfmail@<earlier> prod` + `... latest`. No republish, no version bump.
+
+### Effort
+
+- npmglobalize change: ~5 lines, ~5 minutes.
+- `rebuild.cmd`: one-line edit.
+- `prod.cmd`: 15 lines, fresh file.
+- Test cycle: ~10 minutes.
+
+---
+
+## Approach B — wrapper packages
+
+### Mechanics
+
+Split the current single package into three:
+
+| Name | Role | Versioning |
+|---|---|---|
+| `@bobfrankston/rmfmailapp` | Today's actual code. | Bumps freely on every build. |
+| `@bobfrankston/rmfmail` | Wrapper. `dependencies: { rmfmailapp: "1.0.609" }` pinned. | Bumps only on promotion. |
+| `@bobfrankston/rmfmaildev` | Wrapper. `dependencies: { rmfmailapp: "*" }`. | Tracks rmfmailapp tip. |
+
+Casual user: `npm install -g @bobfrankston/rmfmail` — installs the wrapper, which pulls in the pinned rmfmailapp via npm's normal dependency resolution. Wrapper's `bin` shim invokes rmfmailapp's actual entry point, so the CLI is identical.
+
+Promotion = git commit on the wrapper bumping `dependencies.rmfmailapp` from one frozen version to another, plus `npm publish` of the wrapper.
+
+### Layout
 
-```js
-const npmArgs = ['publish', tarballName];
+```
+mailx/
+  rmfmailapp/                # was app/
+    package.json   "name": "@bobfrankston/rmfmailapp"
+    bin/, packages/, client/  unchanged
+  rmfmail/                   # NEW
+    package.json   pins rmfmailapp version
+    bin/rmfmail.js shim that imports rmfmailapp's entry
+  rmfmaildev/                # NEW
+    package.json   "*" range or always-repinned
+    bin/rmfmaildev.js shim
 ```
 
-Becomes:
+### `rmfmail/package.json`
+
+```json
+{
+  "name": "@bobfrankston/rmfmail",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": { "rmfmail": "bin/rmfmail.js" },
+  "dependencies": { "@bobfrankston/rmfmailapp": "1.0.609" }
+}
+```
+
+### `rmfmail/bin/rmfmail.js`
 
 ```js
-const npmArgs = ['publish', tarballName];
-if (distTag) npmArgs.push('--tag', distTag);
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+await import(`file://${require.resolve("@bobfrankston/rmfmailapp/bin/mailx.js")}`);
 ```
 
-Plus argv parsing for `--dist-tag <name>` (or `--tag`) at the top of the script. ~5 lines total. Default behavior unchanged when the flag is absent — still publishes to `@latest` for every other consumer of npmglobalize.
+### `rmfmaildev/package.json`
 
-### 2. rebuild.cmd
+Same shape but `"@bobfrankston/rmfmailapp": "*"` so npm always resolves to the freshest published rmfmailapp.
 
-Change the npmglobalize invocation to pass `--dist-tag dev`:
+### Required changes
 
-```cmd
-npmglobalize --dist-tag dev
-```
+**1. Rename** `@bobfrankston/rmfmail` → `@bobfrankston/rmfmailapp` in `app/package.json` and any workspace deps that reference it. One-time.
 
-After this, every build that reaches publish goes to `@dev`. `@latest` and `@prod` are frozen at whatever was last promoted.
+**2. Create** `rmfmail/` and `rmfmaildev/` directories with the package.json + shim listed above. ~30 lines total.
 
-### 3. prod.cmd (new file)
+**3. prod.cmd** — bumps the pin and publishes the wrapper:
 
 ```cmd
 @echo off
 setlocal
-for /f "tokens=2 delims=:," %%v in ('findstr /b "  \"version\":" "%~dp0app\package.json"') do set V=%%~v
-set V=%V: =%
-set V=%V:"=%
-echo Promoting @bobfrankston/rmfmail@%V% to prod and latest...
-call npm dist-tag add @bobfrankston/rmfmail@%V% prod
-call npm dist-tag add @bobfrankston/rmfmail@%V% latest
-echo Done. End-users running 'npm install -g @bobfrankston/rmfmail' now get %V%.
+set TARGET=%1
+if "%TARGET%"=="" (
+  for /f "tokens=2 delims=:," %%v in ('findstr /b "  \"version\":" "%~dp0rmfmailapp\package.json"') do set TARGET=%%~v
+  set TARGET=%TARGET: =%
+  set TARGET=%TARGET:"=%
+)
+node -e "const p=require('./rmfmail/package.json'); p.dependencies['@bobfrankston/rmfmailapp']='%TARGET%'; require('fs').writeFileSync('./rmfmail/package.json', JSON.stringify(p,null,2)+'\n');"
+cd rmfmail
+call npm version patch
+call npm publish --access public
+cd ..
+git add rmfmail/package.json
+git commit -m "rmfmail: pin rmfmailapp@%TARGET%"
 endlocal
 ```
 
-(Reads the current `package.json` version. Promotes that version to both `prod` and `latest`. No build, no publish.)
+**4. npmglobalize**: no changes required.
 
-### 4. README / one-liner doc
+### Workflow
 
-User-facing instructions for the two install paths:
+1. Build, run `rebuild.cmd` — publishes rmfmailapp.
+2. Dev install: `npm install -g @bobfrankston/rmfmaildev`. Pulls latest rmfmailapp through the `*` range.
+3. Promotion: `prod.cmd 1.0.611`. Edits rmfmail's pin, bumps wrapper patch version, publishes wrapper, commits.
+4. Casual install: `npm install -g @bobfrankston/rmfmail` resolves the new wrapper, npm fetches the pinned rmfmailapp, both land under the wrapper.
 
-- Stable: `npm install -g @bobfrankston/rmfmail` (gets `@latest` = current prod).
-- Dev: `npm install -g @bobfrankston/rmfmail@dev` (current dev tip).
-- Pin to a specific version: `npm install -g @bobfrankston/rmfmail@1.0.NNN`.
+Roll back: edit rmfmail/package.json to a prior pin, `git revert`, republish wrapper.
 
-## Workflow once wired
+### Effort
 
-1. Edit, build, run `rebuild.cmd` — version bumps, publishes as `@dev`. `@latest`/`@prod` unaffected.
-2. Daily use on the dev machine: `npm install -g @bobfrankston/rmfmail@dev` to grab the freshest build, then run `rmfmail`.
-3. When a recent dev build feels solid, run `prod.cmd`. That single command promotes the *current package.json version* to `prod` + `latest`.
-4. On the prod machine (or any other), `npm install -g @bobfrankston/rmfmail` (no tag) gets the newly-promoted version.
+- One-time rename: ~30 minutes.
+- Wrapper skeletons: ~15 minutes.
+- prod.cmd: ~15 minutes.
+- Test: ~30 minutes.
+- Total: ~1.5 hours up-front, then near-zero per promotion.
 
-Rolling back a bad prod is also a tag move — `npm dist-tag add @bobfrankston/rmfmail@<earlier> prod latest`. No republish; no version-bump needed; old install scripts that pin a version keep working.
+---
 
-## What this does NOT do
+## Comparison
 
-- It does not enable both versions side-by-side on one machine. Single global install per machine; whichever tag was most recently installed wins. Coexistence (separate config dirs / WebView2 dirs / mailto handlers) is the *other* design (`RMFMAIL_PROFILE` env-var pattern, separately).
-- It does not freeze any specific dependency version. Pinning of workspace deps is whatever was bundled at publish time — same as today.
-- It does not change the semantic-version sequence. Both dev and prod publishes share the same monotonic `1.0.N` numbering; the dist-tag is just a movable pointer.
+| | A: dist-tags | B: wrappers |
+|--|--|--|
+| Number of npm packages | 1 | 3 (app + 2 wrappers) |
+| What "promotion" is | `npm dist-tag add` (HTTP call) | git commit + `npm publish` of wrapper |
+| Promotion in git history | no (registry-only) | yes |
+| Roll-back | retag prior version | `git revert` then republish wrapper |
+| npmglobalize change needed | yes (`--tag` flag, ~5 lines) | no |
+| Casual install command | `npm install -g @bobfrankston/rmfmail` | (same) |
+| Dev install command | `... rmfmail@dev` | `... rmfmaildev` |
+| One-time setup work | ~15 minutes | ~1.5 hours |
+| Per-promotion work | seconds (registry call) | minutes (commit + publish) |
+| Multi-channel future (beta, rc) | more dist-tags | more wrappers |
 
-## Effort estimate
+## Recommendation
 
-- npmglobalize change: ~5 lines, ~5 minutes.
-- `rebuild.cmd`: one-line edit.
-- `prod.cmd`: 15 lines, fresh file.
-- Test cycle: publish a dev, verify `@latest` unchanged, run `prod.cmd`, verify `@latest` moved.
+If you want it working today with minimum disturbance: **A (dist-tags)**.
+
+If auditability of "what version was prod when" matters and you're willing to spend the one-time rename: **B (wrappers)**.
+
+A → B migration later is straightforward (the rename and wrapper creation is the same work whenever you do it; dist-tags become a non-issue once wrappers exist).
+
+## What neither approach does
 
-Order of operations: npmglobalize first, then `rebuild.cmd`, then `prod.cmd`. Ship npmglobalize before changing rebuild.cmd to avoid one cycle of "rebuild.cmd uses --dist-tag dev but npmglobalize ignores it and publishes to latest anyway."
+- Does not enable side-by-side coexistence on a single machine — that's the orthogonal `RMFMAIL_PROFILE` env-var design (separate config dir, AUMID, mailto handler, etc.).
+- Does not change the in-app updater. mailx's existing version-check flow keeps working with either.
+- Does not affect Android. APKs aren't on npm — `prod-android.md` is the parallel document with the equivalent channel-manifest design.

package/docs/rmf-tiny.md

@@ -0,0 +1,156 @@
+# `rmf-tiny` — optional TinyMCE editor adapter for rmfmail
+
+Status: design only. Not implemented.
+
+## Goal
+
+Let users who want Thunderbird-class paste fidelity opt into TinyMCE without baking it into rmfmail itself. Bob 2026-05-09 verified: pasted a Word document into Thunderbird, tiptap, Quill, and TinyMCE — only TinyMCE preserved the formatting (boxed monospace block with borders, paragraph spacing, font preservation). Nothing else came close.
+
+The license catch — TinyMCE is GPLv2 — means rmfmail (MIT) can't bundle it. The arms-length pattern is the resolution: rmfmail ships **no** TinyMCE bytes; a separate `rmf-tiny` package the user installs themselves provides the adapter + pulls in TinyMCE via npm.
+
+## Shape
+
+```
+@bobfrankston/rmfmail            ← MIT, ships no TinyMCE
+  client/compose/editor.ts       ← MailxEditor interface + factory
+                                   gains a "tinymce" branch that
+                                   dynamically imports rmf-tiny
+
+@bobfrankston/rmf-tiny           ← MIT (the adapter glue is original code)
+  package.json                   ← peerDependency: tinymce
+  src/adapter.ts                 ← implements MailxEditor against TinyMCE
+  README.md                      ← install instructions
+```
+
+User opts in:
+
+```
+npm install -g @bobfrankston/rmf-tiny tinymce
+```
+
+(Two packages explicit — keeps the licensing posture clean. rmf-tiny is just the adapter; tinymce comes from Tiny's own npm publication, not bundled with anything rmfmail-related.)
+
+In rmfmail Settings → Compose → Editor: the dropdown grows a "TinyMCE (requires rmf-tiny)" option. If selected and the import fails, surface a status-bar error pointing at the install command.
+
+## Why a separate package, not a flag inside rmfmail
+
+- rmfmail's git history and npm tarball never contain TinyMCE → distribution layer is clean.
+- rmf-tiny is small (~200 lines of adapter glue + a thin install README) and can be MIT — no GPL infection because it imports TinyMCE at runtime via the same kind of dynamic boundary npm packages always use. Combination at user's machine is fully GPL-permitted.
+- Other editors can follow the same pattern (`rmf-ckeditor`, `rmf-prosemirror-pro`) without polluting rmfmail.
+
+## Why call it `rmf-tiny`
+
+Short, distinguishable from the upstream package, namespaces under your scope (`@bobfrankston/rmf-tiny`), and "tiny" is the upstream's own brand so the connection is obvious. Other naming options:
+- `@bobfrankston/mailx-tinymce-adapter` (verbose, descriptive)
+- `@bobfrankston/rmftiny` (no hyphen, matches rmfmail style)
+
+`rmf-tiny` is fine; pick the form that scans cleanest in the install line.
+
+## Files
+
+### `rmf-tiny/package.json`
+
+```json
+{
+  "name": "@bobfrankston/rmf-tiny",
+  "version": "0.1.0",
+  "description": "TinyMCE editor adapter for rmfmail. Bring-your-own TinyMCE.",
+  "type": "module",
+  "main": "src/adapter.js",
+  "license": "MIT",
+  "peerDependencies": {
+    "tinymce": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "tinymce": { "optional": false }
+  }
+}
+```
+
+`peerDependencies` puts the install responsibility on the user — `npm install @bobfrankston/rmf-tiny` warns that `tinymce` must also be installed; rmf-tiny does not vendor or bundle TinyMCE.
+
+### `rmf-tiny/src/adapter.ts`
+
+```ts
+// MIT-licensed adapter glue. Imports the user-installed TinyMCE at
+// runtime; doesn't redistribute any TinyMCE bytes. Implements the same
+// `MailxEditor` interface rmfmail's createEditor factory expects, so
+// the host code path is identical.
+import type { Editor as TinyEditor } from "tinymce";
+
+export interface MailxEditor {
+    setHtml(html: string): void;
+    getHtml(): string;
+    getText(): string;
+    focus(): void;
+    setCursor(pos: number): void;
+    root: HTMLElement;
+    // …other methods rmfmail's interface requires
+}
+
+export async function createTinyMceEditor(container: HTMLElement): Promise<MailxEditor> {
+    // Dynamic import — fails clearly if the user hasn't installed tinymce.
+    const tinymce = (await import("tinymce")).default;
+    // Plus the plugins TinyMCE's paste-from-Word handler needs:
+    await Promise.all([
+        import("tinymce/themes/silver"),
+        import("tinymce/icons/default"),
+        import("tinymce/plugins/paste"),
+        import("tinymce/plugins/lists"),
+        import("tinymce/plugins/link"),
+        import("tinymce/plugins/table"),
+        import("tinymce/plugins/code"),
+    ]);
+    // ... initialize tinymce against `container`, return MailxEditor shim.
+}
+```
+
+The actual init/wire-up is the work — wrapping TinyMCE's API in our `MailxEditor` shape, hooking paste events, setHtml/getHtml round-tripping, etc. Maybe ~200 lines.
+
+### rmfmail-side change to `editor.ts`
+
+```ts
+export async function createEditor(
+    container: HTMLElement,
+    type: "quill" | "tiptap" | "tinymce"
+): Promise<MailxEditor> {
+    if (type === "tinymce") {
+        try {
+            const m = await import("@bobfrankston/rmf-tiny");
+            return m.createTinyMceEditor(container);
+        } catch (e: any) {
+            const status = document.getElementById("status-sync");
+            if (status) status.textContent = `TinyMCE editor not available — install: npm install -g @bobfrankston/rmf-tiny tinymce`;
+            return createQuillEditor(container);  // fall back so compose still works
+        }
+    }
+    if (type === "tiptap") return createTiptapEditor(container);
+    return createQuillEditor(container);
+}
+```
+
+Settings panel adds the "TinyMCE" option in the editor dropdown.
+
+## Effort
+
+- `rmf-tiny` package skeleton (package.json, README, basic adapter shell): ~30 minutes.
+- Adapter wiring (init, setHtml/getHtml, paste handling, toolbar config): ~3 hours including testing the Word-paste case.
+- rmfmail-side factory branch + Settings dropdown option: ~30 minutes.
+- Documentation for users (README in rmf-tiny + Settings tooltip): ~30 minutes.
+
+About half a day total.
+
+## Order
+
+1. Build `rmf-tiny` against your local TinyMCE install. Verify the Word-paste case actually works through your adapter.
+2. Add the factory branch and Settings option to rmfmail.
+3. Publish `rmf-tiny` to npm.
+4. Document the opt-in install command in rmfmail's Settings tooltip and `README.md`.
+
+Don't publish the adapter until the Word-paste case actually works end-to-end through the adapter — TinyMCE direct is one thing, our adapter possibly mangles it differently.
+
+## Caveats
+
+- The adapter must not re-implement parts of TinyMCE — it's a thin wrapper. Re-implementing parts of GPL code in MIT is the legal trap; staying purely in adapter / interface territory is safe.
+- TinyMCE's bundle is large (~1MB minified). Users opting in pay that cost on the first compose-window load. Fine for opt-in; would be unacceptable as a default.
+- `rmf-tiny` major version should track TinyMCE's major version (rmf-tiny@7.x for tinymce@7.x) so peerDependency mismatches are obvious.