avancement planning

node_modules/@npmcli/package-json/README.md

@@ -144,6 +144,10 @@ Like `normalize` but intended for preparing package.json files for publish.
 
 ---
 
+### `PackageJson.syncNormalize()`
+
+This calls normalize synchronously.  Most consumers of this package should avoid using this.  It was added because some parts of npm were normalizing package content in class constructors and needed this affordance.  It will silently ignore any asynchronous steps asked for.  Again, this is a compatiblity affordance for some code in npm that is currently impossible to change without a significant semver major change, and is best not used.
+
 ### **static** `async PackageJson.prepare(path, opts = {})`
 
 Convenience static that calls `load` before calling `prepare`
@@ -233,10 +237,20 @@ pkgJson.content
 
 ---
 
-### `async PackageJson.save()`
+### `async PackageJson.save([options])`
 
-Saves the current `content` to the same location used when calling
-`load()`.
+
+Saves the current `content` to the same location used when calling `load()`.
+
+- `options`: `Object` (optional)
+  - `sort`: `Boolean` (optional) — If true, sorts the keys in the resulting `package.json` file for consistency and readability.
+
+> [!NOTE]
+> The sort order for `package.json` is based on the conventions from
+> [sort-package-json](https://github.com/keithamus/sort-package-json/blob/main/defaultRules.md),
+> cross-checked with the official npm types and documentation:
+> - https://github.com/npm/types/blob/main/types/index.d.ts#L104
+> - https://docs.npmjs.com/cli/configuring-npm/package-json
 
 ## LICENSE