diff --git a/README.md b/README.md
index 4fdda1b..9999446 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,68 @@ code. Package managers are a developing landscape for Lua in the context of
NeoVim. Perhaps in the future, `lux` will eliminate the need to vendor this
library in your application code.
+#### If you are a Plugin Author
+
+Neovim does not have a good answer for automatic management of plugin dependencies. As such, it is recommended that library authors vendor u.nvim within their plugin. **u.nvim** is implemented in a single file, so this should be relatively painless. Furthermore, `lua/u.lua` versions are published into artifact tags `artifact-vX.Y.Z` as `init.lua` so that plugin authors can add u.nvim as a submodule to their plugin.
+
+
+Example git submodule setup
+
+```bash
+# In your plugin repository
+git submodule add -- https://github.com/jrop/u.nvim lua/my_plugin/u
+cd lua/my_plugin/u/
+git checkout artifact-v0.2.0 # put whatever version of u.nvim you want to pin here
+# ... commit the submodule within your repo
+
+# This would place u.nvim@v0.2.0 at:
+# lua/my_plugin/u/init.lua
+```
+
+Then in your plugin code:
+
+```lua
+local u = require('my_plugin.u')
+
+local Pos = u.Pos
+local Range = u.Range
+-- etc.
+```
+
+This approach allows plugin authors to:
+- Pin to specific versions of u.nvim
+- Get updates by pulling/committing new **u.nvim** versions (i.e., the usual git submodule way)
+- Keep the dependency explicit and version-controlled
+- Avoid namespace conflicts with user-installed plugins
+
+
+
+#### If you are a User
+
+If you want to use u.nvim in your config directly:
+
+
+vim.pack
+
+```lua
+vim.pack.add { 'https://github.com/jrop/u.nvim' }
+```
+
+
+
+
+lazy.nvim
+
+```lua
+{
+ 'jrop/u.nvim',
+ lazy = true,
+}
+```
+
+
+
+
## Signal and Rendering Usage
### Overview
diff --git a/mise.toml b/mise.toml
index 6cc41da..c413566 100644
--- a/mise.toml
+++ b/mise.toml
@@ -14,7 +14,7 @@ jq = "1.8.1"
# installed. In the tests, we will override with `eval $(nvimv env VERSION)`,
# but to avoid having to litter a bunch of commands with that environment
# initialization, this just makes things simpler:
-neovim = "0.12.0"
+neovim = "0.12.1"
stylua = "2.3.1"
"cargo:emmylua_ls" = "0.20.0"
"cargo:emmylua_check" = "0.20.0"
@@ -79,12 +79,12 @@ arg "" help="The version of Neovim to test with"
run = 'mise test:version:no-prep $usage_version'
[tasks."test"]
-run = 'mise test:version 0.12.0'
+run = 'mise test:version 0.12.1'
[tasks."test:all"]
depends = ["test:prepare"]
run = '''
-VERSIONS="0.11.5 0.12.0 nightly"
+VERSIONS="0.11.5 0.12.1 nightly"
for v in $VERSIONS; do
mise test:version:no-prep $v
done
diff --git a/scripts/make-artifact-tag.sh b/scripts/make-artifact-tag.sh
new file mode 100755
index 0000000..f9d7fb7
--- /dev/null
+++ b/scripts/make-artifact-tag.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# After tagging a release (say, v1.2.3), use this script to publish
+# lua/u.lua in an artifact branch: artifact-v1.2.3:init.lua. To do so,
+# invoke the script from the root of the repo like so:
+#
+# ./scripts/make-artifact-tag.sh v1.2.3
+#
+# This will create a temporary orphan branch, tag it and immediately delete the
+# branch.
+#
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+ echo "Usage: $0 "
+ exit 1
+fi
+
+TAG="$1"
+if [[ "$(echo "$TAG" | awk '/^v[0-9]+\.[0-9]+\.[0-9]+$/ { print "YES" }')" != "YES" ]]; then
+ echo "Invalid tag name: expected 'vX.Y.Z'"
+ exit 1
+fi
+
+ARTIFACT_TAG="artifact-$TAG"
+EXISTING_ARTIFACT_TAG=$(git tag -l "$ARTIFACT_TAG")
+
+if [[ "$ARTIFACT_TAG" = "$EXISTING_ARTIFACT_TAG" ]]; then
+ echo "Artifact tag already exists"
+ exit 1
+fi
+
+git worktree add --orphan -b "$ARTIFACT_TAG" "$ARTIFACT_TAG"
+git cat-file -p "$TAG":lua/u.lua > "$ARTIFACT_TAG"/init.lua
+
+pushd "$ARTIFACT_TAG"
+git add --all
+git commit --message "$ARTIFACT_TAG"
+git tag "$ARTIFACT_TAG"
+popd
+
+git worktree remove -f "$ARTIFACT_TAG"
+git branch -D "$ARTIFACT_TAG"