docs: add README, changelog, and vim help

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-09
+
+### Added
+
+- Initial release
+- Centered floating progress bar with 60fps smooth animation
+- Post-update results via snacks.nvim picker (ivy layout)
+- Floating markdown fallback when snacks.nvim is unavailable
+- Commit log preview per changed plugin
+- Rollback detection (labels commits when a plugin moves backward)
+- Auto-update cadence: `manual`, `daily`, `weekly`, `monthly`
+- `TinyPackProgress` highlight group (links to `DiagnosticOk` by default)
+- Configurable command name via `command` option
+- `picker` option to force fallback UI for testing
+
+[0.1.0]: https://github.com/swaits/tiny-packupdate.nvim/releases/tag/v0.1.0

README.md

@@ -0,0 +1,112 @@
+# tiny-packupdate.nvim
+
+A tiny, opinionated plugin updater for Neovim 0.12+'s native `vim.pack`.
+
+Smooth animated progress bar. Commit-level changelogs.
+[snacks.nvim](https://github.com/folke/snacks.nvim) picker integration with
+floating markdown fallback. ~250 lines of Lua.
+
+https://github.com/user-attachments/assets/TODO-SCREENCAST
+
+## Features
+
+- Centered floating progress bar with smooth 60fps animation
+- Post-update results showing only plugins that changed
+- Commit log preview per plugin (with rollback detection)
+- [snacks.nvim](https://github.com/folke/snacks.nvim) picker with git-highlighted preview pane
+- Floating markdown window fallback when snacks is unavailable
+- Auto-update cadence: `manual`, `daily`, `weekly`, or `monthly`
+- Single command, single file, zero dependencies
+
+## Requirements
+
+- Neovim >= 0.12 (for `vim.pack` API)
+- Optional: [snacks.nvim](https://github.com/folke/snacks.nvim) for picker UI
+
+## Installation
+
+Add to your `vim.pack.add()` call:
+
+```lua
+"https://github.com/swaits/tiny-packupdate.nvim",
+```
+
+Then in your config:
+
+```lua
+require("tiny-packupdate").setup()
+```
+
+## Configuration
+
+All options shown with defaults:
+
+```lua
+require("tiny-packupdate").setup({
+  command = "PackUpdate", -- user command name
+  auto = "manual",        -- "manual" | "daily" | "weekly" | "monthly"
+  picker = true,          -- use snacks.picker when available (false = always use fallback)
+})
+```
+
+## Usage
+
+```vim
+:PackUpdate
+```
+
+The progress bar appears while `vim.pack.update()` runs. When complete:
+
+- **With snacks.nvim**: an ivy-layout picker opens. Plugin names on the left,
+  commit log on the right. Fuzzy-searchable.
+- **Without snacks.nvim**: a floating markdown window shows all changes.
+  Press `q` or `<Esc>` to close.
+- **No changes**: a simple notification — "All plugins up to date".
+
+### Auto-update
+
+Set `auto` to `"daily"`, `"weekly"`, or `"monthly"` and updates run
+automatically on startup when the interval has elapsed. The last update
+timestamp is stored at `vim.fn.stdpath("data") .. "/tiny-packupdate-last"`.
+
+## Highlights
+
+| Group | Default | Description |
+|---|---|---|
+| `TinyPackProgress` | links to `DiagnosticOk` | Filled portion of the progress bar |
+
+Override in your colorscheme or after setup:
+
+```lua
+vim.api.nvim_set_hl(0, "TinyPackProgress", { fg = "#a6e3a1" })
+```
+
+## How it works
+
+1. Snapshots all active plugin revisions via `vim.pack.get()`
+2. Calls `vim.pack.update()` with `force = true`
+3. Listens for `PackChanged` autocmd events to count updates
+4. Uses a 2-second debounce timer to detect completion
+5. Compares post-update revisions against the snapshot
+6. Runs async `git log` for each changed plugin
+7. Displays results in your preferred UI
+
+### Rollback detection
+
+When a plugin moves backward in history (e.g. downgrading a pinned version),
+the commit log is labeled `(rolled back past)` and shows the commits that were
+reverted.
+
+## Caveats
+
+- Only updates plugins already loaded via `vim.pack.add()`. If you just added a
+  new plugin to your config but haven't restarted, it won't be included.
+- The progress bar is time-based (smooth asymptotic fill). Neovim's `vim.pack`
+  API fires `PackChanged` events only for plugins that actually change, so a
+  traditional done/total bar isn't possible.
+- The debounce timeout (2 seconds) means there's a brief pause after the last
+  plugin updates before results appear.
+
+## License
+
+[MIT](LICENSE)

doc/tiny-packupdate.txt

@@ -0,0 +1,92 @@
+*tiny-packupdate.txt*  Minimal vim.pack updater with progress bar & results picker
+
+Author: Stephen Waits <https://github.com/swaits>
+License: MIT
+
+==============================================================================
+CONTENTS                                          *tiny-packupdate-contents*
+
+  1. Introduction ............................ |tiny-packupdate-introduction|
+  2. Requirements ............................ |tiny-packupdate-requirements|
+  3. Installation ............................ |tiny-packupdate-installation|
+  4. Configuration ........................... |tiny-packupdate-configuration|
+  5. Commands ................................ |tiny-packupdate-commands|
+  6. Highlights .............................. |tiny-packupdate-highlights|
+
+==============================================================================
+1. INTRODUCTION                                *tiny-packupdate-introduction*
+
+tiny-packupdate.nvim is a minimal plugin updater for Neovim 0.12+'s native
+|vim.pack| API. It provides a smooth animated progress bar, commit-level
+changelogs, and an optional snacks.nvim picker for browsing results.
+
+==============================================================================
+2. REQUIREMENTS                                *tiny-packupdate-requirements*
+
+- Neovim >= 0.12 (for |vim.pack| API)
+- Optional: snacks.nvim (https://github.com/folke/snacks.nvim) for picker UI
+
+==============================================================================
+3. INSTALLATION                                *tiny-packupdate-installation*
+
+Add to your |vim.pack.add()| call: >lua
+
+    "https://github.com/swaits/tiny-packupdate.nvim",
+<
+Then in your config: >lua
+
+    require("tiny-packupdate").setup()
+<
+==============================================================================
+4. CONFIGURATION                              *tiny-packupdate-configuration*
+
+                                                  *tiny-packupdate.setup()*
+setup({opts})
+
+    All options shown with defaults: >lua
+
+        require("tiny-packupdate").setup({
+          command = "PackUpdate",  -- user command name
+          auto = "manual",         -- "manual"|"daily"|"weekly"|"monthly"
+          picker = true,           -- use snacks.picker when available
+        })
+<
+    Parameters: ~
+      {opts}  (table|nil) Configuration table
+
+    Fields: ~
+      {command}  (string) Name of the user command. Default: "PackUpdate"
+      {auto}     (string) Auto-update cadence. One of:
+                   "manual"  - no automatic updates (default)
+                   "daily"   - update once per day on startup
+                   "weekly"  - update once per week on startup
+                   "monthly" - update once per month on startup
+      {picker}   (boolean) Use snacks.nvim picker when available.
+                   Set to false to always use the floating markdown fallback.
+                   Default: true
+
+==============================================================================
+5. COMMANDS                                        *tiny-packupdate-commands*
+
+                                                              *:PackUpdate*
+:PackUpdate
+    Update all active plugins via |vim.pack.update()|. Shows a floating
+    progress bar during the update and displays results when complete.
+
+    Only plugins loaded via |vim.pack.add()| in the current session are
+    included. Running this command while an update is already in progress
+    shows a warning.
+
+==============================================================================
+6. HIGHLIGHTS                                    *tiny-packupdate-highlights*
+
+TinyPackProgress                                          *hl-TinyPackProgress*
+    Highlight group for the filled portion of the progress bar.
+    Default: links to |hl-DiagnosticOk|
+
+    Override example: >lua
+
+        vim.api.nvim_set_hl(0, "TinyPackProgress", { fg = "#a6e3a1" })
+<
+==============================================================================
+vim:tw=78:ts=8:ft=help:norl: