Update README.md

Author: bep

README.md

@@ -1,8 +1,57 @@
+# npmtohugomod
 
-## Module wrapper versioning
+A small tool that wraps npm packages as Hugo Modules, so a Hugo site can
+consume them without an npm dependency.
+
+Given a `package.json` with a `dependencies` block, it downloads each package
+from the npm registry, drops it into a per-package directory with a `go.mod`
+and `hugo.toml`, and writes a root `hugo.toml` that re-exports all of them
+as a single Hugo Module.
+
+## Usage
+
+Run it from the root of a git repo that will host the wrappers. The Go
+module base path is derived from the repo's `origin` remote.
+
+```sh
+# Sync wrappers from ./package.json
+npmtohugomod
+
+# Override the module base path (skip git-remote auto-detection)
+npmtohugomod --module-base github.com/owner/repo
+```
+
+Re-runs with an unchanged `package.json` are no-ops; on a version bump only
+the affected package is refetched. Requires `hugo` and `git` on `PATH`.
 
-We use a simple versioning scheme where the the upstream controls the major and minor version and `W` gets incremented whenever something in the wrapper changes (e.g. `hugo.toml` config update):
+## What gets generated
 
->vX.Y.(Z*1000+W)
+For each entry in `dependencies` (e.g. `@alpinejs/focus`):
+
+- `alpinejs/focus/package/…` — the npm tarball contents.
+- `alpinejs/focus/npmpackage.json` — npm metadata (informational).
+- `alpinejs/focus/hugo.toml` — mounts the ESM build under `assets/@alpinejs/focus`.
+- `alpinejs/focus/go.mod` — created by `hugo mod init`. For majors ≥ 2 the module path includes a `/vN` suffix (Go semantic import versioning).
+- `alpinejs/focus/README.md` — has a marker-delimited block showing the import path; updates regenerate just that block, anything outside is preserved.
+
+At the repo root, `hugo.toml` lists every wrapper as a `[[module.imports]]`
+entry, so a downstream Hugo site can import the whole bundle in one line.
+
+## Releasing
+
+```sh
+npmtohugomod release
+```
+
+Walks all wrapper directories and creates a local annotated git tag for each
+(then stops — tags are **not** pushed). Existing tags are skipped, so re-runs
+are safe. Fails if the working tree is dirty; pass `--allow-dirty` to
+override.
+
+## Module wrapper versioning
 
-`W` starts at 0 and resets on any upstream-change.
+Tags follow `vX.Y.(Z*1000+W)`, where `X.Y.Z` is the upstream npm version and
+`W` is bumped on wrapper-only changes (e.g. a `hugo.toml` tweak). `W` starts
+at 0 and resets on any upstream-version change. The release command
+currently always emits `W=0`; re-tagging after a wrapper-only change is
+manual for now.