Bring commands-implementation-details up to date

Document every command (adds pre, tag, info, ui, shell-init) and correct
the stale sections: add now lists its flags, publish describes the
registry-aware behavior (not the old git-diff approach), and status
describes the grouped plan. Add an interop/front-door delegation section
and note the changelog generators.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: JohnCampionJr

docs/commands-implementation-details.md

@@ -1,93 +1,151 @@
 # Commands implementation details
 
-On this page, we will discuss implementation details that differ slightly from the original changeset implementation [@changesets/cli](https://github.com/changesets/changesets/tree/main).
+This page covers each net-changesets command and where its behaviour differs from the original
+[`@changesets/cli`](https://github.com/changesets/changesets/tree/main). All commands share the
+`.changeset/config.json` schema described in [config-file-options.md](config-file-options.md).
 
 ## `init`
 
 ```bash
 changeset init
 ```
 
-This command works the same, only difference is that we have different configuration schema to satisfy .NET implementation. You can read more about it in [config-file-options.md](https://github.com/solarwinds/net-changesets/blob/main/docs/config-file-options.md).
+Creates the `.changeset` folder and a `config.json`. The only difference from `@changesets` is the
+configuration schema, which adds a `dotnet` section for the .NET-only settings (see
+[config-file-options.md](config-file-options.md)).
 
 ## `add`
 
 ```bash
-changeset add
+changeset add        # or just `changeset` (add is the default command)
 ```
 
-or just (`add` is the default command)
+Discovers projects, prompts for which changed, the bump type, and a summary, then writes a changeset to
+`.changeset/<random-name>.md`. Options:
+
+- `--empty` — writes a changeset with no releases (useful to force a release run).
+- `-m`, `--message <summary>` — supplies the summary instead of prompting.
+- `--open` — opens the new changeset in your editor (`$VISUAL` / `$EDITOR`).
+- `--since <ref>` — pre-selects the projects that changed since a git ref.
+
+Differences from `@changesets`: a single bump type is chosen for all selected projects (the Node version
+allows a different bump per project); in interop mode the file is written with the
+[`changesetExtension`](config-file-options.md#changesetextension) (default `.net.mkd`).
+
+## `version`
 
 ```bash
-changeset
+changeset version
+changeset version --snapshot [tag]
+changeset version --independent
 ```
 
-This is the default command when running Changesets without specifying a command.
-Currently, the tool does not support any command-line options and runs only in interactive mode.
-The changeset file name is randomly generated using lowercase letters from the English alphabet.
+Consumes changesets, bumps versions, writes `CHANGELOG.md` files, and (by default) deletes the processed
+changesets. It also bumps every project that depends (via `ProjectReference`) on a changed project — always by
+a patch, because a `ProjectReference` carries no version range (matching `@changesets` for out-of-range
+dependencies).
+
+- **Changelog generator** — honours the [`changelog` config key](config-file-options.md#changelog): the
+  default format, `changelog-git` (short commit-hash prefix), or `changelog-github` (PR/commit links and
+  author thanks). Dependency-update lines always use the default format.
+- **Snapshot** — `--snapshot [tag]` writes `0.0.0-<tag>-<datetime>` (or the calculated base when
+  `snapshot.useCalculatedVersion` is set) and consumes the changesets without entering prerelease state.
+- **Prerelease** — in `pre` mode it writes `x.y.z-<tag>.<n>` versions, keeps the changesets, and records the
+  consumed ids in `pre.json`.
+- **Shared versions** — projects whose version comes from a shared `Directory.Build.props` move together
+  (`lockstep`), unless `--independent` (or `versionStrategy`) writes an inline `<Version>` per project.
+- **No .NET projects** — guides you to the Node tool (or, with `autoRunNode`, delegates to it; see
+  [Interop and the front door](#interop-and-the-front-door)) and leaves changesets untouched.
+
+In interop mode, only changesets that name .NET projects are processed; a Node-only changeset is left in place,
+and a shared changeset keeps its Node remainder for the Node tool.
 
-How it works
+## `status`
 
-- The command reads all .csproj project files from the SourcePath.
-- It prompts the user with a multi-select option to choose which projects have changed.
-- It prompts the user to select the type of change (patch, minor, or major).
-- It prompts the user to describe what has changed.
-- It generates a changeset file with the selected projects, change type, and description and stores it in `.changeset` folder.
+```bash
+changeset status
+changeset status --verbose
+changeset status --output <file>
+changeset status --since <ref>
+```
 
-Notes
-The only difference compared to the Node.js implementation is that this version currently supports selecting only a single change type for all selected projects.
-The Node.js version allows selecting a different change type for each project individually.
-This additional functionality can be implemented easily if needed.
+Prints the pending release plan — the packages to be bumped, grouped by bump level (and, in interop mode, by
+ecosystem). `--verbose` shows each package's new version and the changeset files driving it; `--output` writes
+the plan as JSON instead of printing it; `--since` narrows the changesets to those added since a ref. Exits
+with a non-zero code when there are no changesets. Differs from `@changesets`, whose default output is a
+simpler summary.
 
-## `version`
+## `pre`
 
 ```bash
-changeset version
+changeset pre enter <tag>
+changeset pre exit
 ```
 
-If there are any existing changesets the command generates changelogs for every project dependent on the updated project. It also amends SemVer version of the affected project.
+Enters or exits prerelease mode by writing `.changeset/pre.json`. While in pre mode, `version` produces
+`x.y.z-<tag>.<n>` versions and keeps changesets; `pre exit` clears the state so the next `version` graduates to
+stable versions.
 
-## `publish`
+## `tag`
 
 ```bash
-changeset publish
+changeset tag
 ```
 
-Creates NuGet packages of affected projects and publishes them to the predefined package source.
+Creates a git tag per project at its current version (`<package-id>@<version>`, using the project's
+`PackageId` when set), skipping tags that already exist. Useful after `version` to tag a release.
 
-### How it works (current .NET implementation)
-
-Currently, the `publish` command assumes that the changes made by the `version` command have **already been committed**. The intended flow is:
+## `publish`
 
-1. Run `changeset version` to bump versions, update changelogs, and delete processed changesets.
-2. Commit the changes produced by the `version` command.
-3. Run `changeset publish` to create and push NuGet packages based on the committed changes.
+```bash
+changeset publish
+changeset publish --no-git-tag
+```
 
-The `publish` command does following:
+Packs every discovered project with `dotnet pack` and pushes with `dotnet nuget push --skip-duplicate` to the
+configured `packageSource`, then creates any missing git tags (unless `--no-git-tag`).
 
-1. Gets all modified `.csproj` files from the predefined source directory by comparing the last two commits `git diff --name-only HEAD~1 HEAD {sourcePath}`
-2. For each changed `.csproj` file, creates a NuGet package using `dotnet pack`.
-3. Pushes the created NuGet packages to the predefined NuGet source using `dotnet nuget push`.
+Unlike the original net-changesets approach (which compared `git diff HEAD~1 HEAD`), publish is now
+**registry-aware**, matching `@changesets`: it asks the feed which versions already exist and packs/pushes only
+the projects whose current version is missing. This makes publish idempotent and order-independent — it makes
+no assumption about which commit ran `version`. When the feed cannot be queried, the project is packed and the
+feed's `--skip-duplicate` dedupes.
 
-The package source can be configured via the `.changeset/config.json` file (see `docs/config-file-options.md`).
+## `info`
 
-This approach relies on the fact that the `version` command only performs three types of changes:
+```bash
+changeset info
+```
 
-- Deleting processed changeset files from the `.changeset` folder
-- Modifying or creating `CHANGELOG.md` files
-- Bumping versions in `.csproj` files
+Prints the resolved configuration, the discovered projects (and any skipped for lacking a version), and the
+count of pending changesets broken down by ecosystem. A diagnostic to confirm net-changesets sees your repo as
+expected.
 
-By looking at the diff between `HEAD~1` and `HEAD`, `publish` can safely identify which projects had their versions bumped and therefore need to be published.
+## `ui`
 
-### Comparison with original Node.js changesets implementation
+```bash
+changeset ui
+```
 
-The original `@changesets/cli` implementation for Node.js works differently. Instead of relying on a Git diff,
-it checks whether a package with the **current version** from `package.json` already exists in the package registry; if it does not, the package is published.
+An interactive menu that dispatches the other commands — a convenience entry point.
 
-## `status`
+## `shell-init`
 
 ```bash
-changeset status
+changeset shell-init [zsh|bash|pwsh]
 ```
 
-The command writes number of changesets in the `.changeset` folder to the console.
+Prints a shell snippet that defines a `changeset-net` function pointing at the net-changesets binary, so you
+can invoke net even when the shared `changeset` command resolves to the Node tool on your `PATH`. Run with no
+shell argument for setup instructions. See the
+["Using alongside @changesets" README section](../README.md#using-alongside-changesets-node).
+
+## Interop and the front door
+
+When [`interop`](config-file-options.md#interop) is on, net-changesets and the Node `@changesets` tool share
+one `.changeset/` folder: net versions only .NET projects and never deletes a Node changeset. With
+[`autoRunNode`](config-file-options.md#autorunnode), net becomes a front door — `version`, `status`, and
+`publish` run the Node tool ([`nodeChangesetCommand`](config-file-options.md#nodechangesetcommand)) after their
+own pass, and in a repository with no .NET projects they delegate to it entirely (`version` passes a snapshot
+tag through). A loop guard, set on the Node child process only, prevents infinite recursion if
+`nodeChangesetCommand` is misconfigured to resolve back to net.