Document Joplin plugin publishing workflow

README.md

@@ -403,11 +403,54 @@ Design notes and the full specification live in [SPEC.md](SPEC.md). Release hist
 
 ### Cutting a release
 
-1. Bump `version` in `src/manifest.json`, `package.json`, and `package-lock.json` (the manifest and package versions must match).
+Joplin discovers plugins from npm and imports qualifying packages into its
-2. Add an entry to `CHANGELOG.md`.
+official plugin repository automatically. A separate pull request to
-3. `npm publish` (the `prepare` script rebuilds the `.jpl` fresh from source, so you can't accidentally publish a stale build).
+`joplin/plugins` is not normally required.
 
-If `npm publish` fails with `E404` on the `PUT`, check `npm whoami` first — a 401 there means your login session has expired, which npm surfaces as a misleading 404 on publish. Fix with `npm login --auth-type=legacy`, or avoid it entirely with a [granular access token](https://docs.npmjs.com/creating-and-viewing-access-tokens) so publishing never needs an interactive session.
+1. Bump `version` in `src/manifest.json`, `package.json`, and the root package
+   entries in `package-lock.json`. All versions must match.
+2. Finish the release entry in `CHANGELOG.md`, commit the release, and push it.
+3. Sign in to npm and confirm the expected account and public registry:
+
+   ```bash
+   npm login
+   npm whoami
+   npm config get registry
+   ```
+
+   Publishing requires npm two-factor authentication or a granular access token
+   that is permitted to publish.
+4. Confirm the version has not already been published, then build and inspect
+   the exact package contents:
+
+   ```bash
+   npm view joplin-plugin-gtd-calendar@VERSION version
+   npm run dist
+   npm pack --dry-run
+   ```
+
+   The dry run must include `package.json`, this README, and matching `.jpl` and
+   `.json` files under `publish/`. Verify that the JSON manifest and JPL manifest
+   both contain the intended version. Published npm name/version pairs are
+   immutable, so a version cannot be corrected and reused after publication.
+5. Publish publicly and verify npm's `latest` tag:
+
+   ```bash
+   npm publish --access public
+   npm view joplin-plugin-gtd-calendar@VERSION
+   npm view joplin-plugin-gtd-calendar dist-tags
+   ```
+
+The `prepare` lifecycle rebuilds the `.jpl` during `npm publish`. This package's
+name begins with `joplin-plugin-`, its npm keywords include `joplin-plugin`, and
+its `publish/` directory contains the `.jpl` and `.json` required by Joplin's
+importer. The official repository refreshes about every 30 minutes; after
+publishing, confirm the release appears on
+[Joplin Plugins](https://joplinapp.org/plugins/) and in Joplin's plugin search.
+
+If publishing fails with an authentication-looking `E404` or `E401`, run
+`npm whoami` and sign in again. If the package already exists, the signed-in npm
+account must be one of its maintainers.
 
 ## Credits & license