zuqini · Aug 20, 2026 · Aug 20, 2026
diff --git a/docs/examples.md b/docs/examples.md
@@ -1,5 +1,22 @@
 # Spec Examples
 
+- [Plugin Spec](#plugin-spec)
+- [Lazy Load on Command](#lazy-load-on-command)
+- [Lazy Load on Keymap](#lazy-load-on-keymap)
+- [Lazy Load on Event](#lazy-load-on-event)
+- [Lazy Load on Event with Pattern](#lazy-load-on-event-with-pattern)
+- [Lazy Load on FileType](#lazy-load-on-filetype)
+- [Conditional Loading](#conditional-loading)
+- [Build Hook](#build-hook)
+- [Dependencies](#dependencies)
+- [Version Pinning](#version-pinning)
+  - [Version Pinning for lazy.nvim compatibility](#version-pinning-for-lazynvim-compatibility)
+- [Load Priority](#load-priority)
+- [Using Plugin Data in Hooks](#using-plugin-data-in-hooks)
+- [Explicit Main Module](#explicit-main-module)
+- [Multiple Plugins in One File](#multiple-plugins-in-one-file)
+- [Real-World Config](#real-world-config)
+
 #### Plugin Spec
 
 ```lua

diff --git a/docs/spec.md b/docs/spec.md
@@ -1,5 +1,13 @@
 # Spec Reference
 
+- [zpack.Spec Reference](#zpackspec-reference)
+- [zpack.Plugin Reference](#zpackplugin-reference)
+- [zpack.EventSpec Reference](#zpackeventspec-reference)
+- [zpack.KeySpec Reference](#zpackkeyspec-reference)
+- [zpack.PluginInfo Reference](#zpackplugininfo-reference)
+
+### zpack.Spec Reference
+
 ```lua
 {
   -- Plugin source (provide at least one; src > url > dir > [1])

diff --git a/docs/tips.md b/docs/tips.md
@@ -1,32 +1,13 @@
 # Tips & Migration
 
-## Upgrading from 1.x to 2.0
-
-2.0.0 removes every option and command that was deprecated during the 1.x series. The renamed options (`confirm`, `disable_vim_loader`, `plugins_dir`) emitted runtime warnings throughout 1.x; the legacy `:Z*` commands are removed in favor of the `:ZPack <subcommand>` dispatcher. Removed options are now ignored silently, so update your `setup()` call before upgrading:
-
-| Removed in 2.0 | Replacement |
-|---|---|
-| `setup({ confirm = … })` | `setup({ defaults = { confirm = … } })` |
-| `setup({ disable_vim_loader = true })` | `setup({ performance = { vim_loader = false } })` |
-| `setup({ plugins_dir = 'dir' })` | a `{ import = 'dir' }` entry in your spec list |
-| `setup({ cmd_prefix = 'Z' })` | `setup({ cmd_name = 'Z' })` |
-| `setup({ auto_import = … })` | removed — was already a no-op in 1.x |
-| `require('zpack').add(…)` | removed — was already a no-op in 1.x |
-
-### Commands
-
-The per-action `:Z*` commands are now subcommands of a single `:ZPack` command:
-
-| 1.x | 2.0 |
-|---|---|
-| `:ZUpdate` | `:ZPack update` |
-| `:ZRestore` | `:ZPack restore` |
-| `:ZClean` | `:ZPack clean` |
-| `:ZBuild` | `:ZPack build` |
-| `:ZLoad` | `:ZPack load` |
-| `:ZDelete` | `:ZPack delete` |
-
-The command name is configurable via `cmd_name` (default `ZPack`). If you relied on the old `cmd_prefix = 'Z'`, set `cmd_name = 'Z'` to type `:Z update`, `:Z clean`, etc. The `!` bang is still supported where it was before (e.g. `:ZPack! build`, `:ZPack! delete`).
+- [Migrating from lazy.nvim](#migrating-from-lazynvim)
+- [Gotchas](#gotchas)
+- [Compatibility Notes](#compatibility-notes)
+  - [Snacks.nvim dashboard with zpack.nvim](#snacksnvim-dashboard-with-zpacknvim)
+  - [noice.nvim with vim.pack](#noicenvim-with-vimpack)
+- [Lockfile location](#lockfile-location)
+- [Native vim.pack commands](#native-vimpack-commands)
+- [Upgrading from 1.x to 2.0](#upgrading-from-1x-to-20)
 
 ## Migrating from lazy.nvim
 
@@ -100,3 +81,31 @@ zpack needs no configuration for this — it delegates to `vim.pack` for lockfil
 ## Native vim.pack commands
 
 On Neovim 0.13+, the `:ZPack update`, `restore`, and `delete` subcommands have native `vim.pack` command equivalents (`:packupdate`, `:packupdate ++lockfile`, `:packdel`). Use whichever you prefer — zpack keeps its session state in sync either way. See `:h zpack-native-commands` for the full mapping.
+
+## Upgrading from 1.x to 2.0
+
+2.0.0 removes every option and command that was deprecated during the 1.x series. The renamed options (`confirm`, `disable_vim_loader`, `plugins_dir`) emitted runtime warnings throughout 1.x; the legacy `:Z*` commands are removed in favor of the `:ZPack <subcommand>` dispatcher. Removed options are now ignored silently, so update your `setup()` call before upgrading:
+
+| Removed in 2.0 | Replacement |
+|---|---|
+| `setup({ confirm = … })` | `setup({ defaults = { confirm = … } })` |
+| `setup({ disable_vim_loader = true })` | `setup({ performance = { vim_loader = false } })` |
+| `setup({ plugins_dir = 'dir' })` | a `{ import = 'dir' }` entry in your spec list |
+| `setup({ cmd_prefix = 'Z' })` | `setup({ cmd_name = 'Z' })` |
+| `setup({ auto_import = … })` | removed — was already a no-op in 1.x |
+| `require('zpack').add(…)` | removed — was already a no-op in 1.x |
+
+### Commands
+
+The per-action `:Z*` commands are now subcommands of a single `:ZPack` command:
+
+| 1.x | 2.0 |
+|---|---|
+| `:ZUpdate` | `:ZPack update` |
+| `:ZRestore` | `:ZPack restore` |
+| `:ZClean` | `:ZPack clean` |
+| `:ZBuild` | `:ZPack build` |
+| `:ZLoad` | `:ZPack load` |
+| `:ZDelete` | `:ZPack delete` |
+
+The command name is configurable via `cmd_name` (default `ZPack`). If you relied on the old `cmd_prefix = 'Z'`, set `cmd_name = 'Z'` to type `:Z update`, `:Z clean`, etc. The `!` bang is still supported where it was before (e.g. `:ZPack! build`, `:ZPack! delete`).