zuqini · zuqini · May 25, 2026 · May 25, 2026 · May 25, 2026 · May 25, 2026
diff --git a/README.md b/README.md
@@ -70,13 +70,15 @@ zpack provides a single user command, `:ZPack`, with subcommands. The command
 name is configurable via the `cmd_name` option — a short name like `Z` or `Zp`
 is recommended for ease of use.
 
-- `:ZPack[!] update [plugin]` - Update all plugins, or a specific plugin if provided (supports tab completion). `!` applies updates immediately, skipping the confirmation buffer. See `:h vim.pack.update()`
+- `:ZPack[!] update [plugin]` - Update all plugins, or a specific plugin if provided (supports tab completion). `!` applies updates immediately, skipping the confirmation buffer. Honors `pin = true` for bulk updates. See `:h vim.pack.update()`
 - `:ZPack[!] restore [plugin]` - Restore all plugins, or a specific plugin, to the lockfile state (supports tab completion). `!` applies the restore immediately, skipping the confirmation buffer. Requires a lockfile to exist (created automatically by `:ZPack update`). See `:h vim.pack.update()`
 - `:ZPack clean` - Remove plugins that are no longer in your spec
 - `:ZPack[!] build [plugin]` - Run build hook for a specific plugin, or all plugins with `!` (supports tab completion)
 - `:ZPack[!] load [plugin]` - Load a specific unloaded plugin, or all unloaded plugins with `!` (supports tab completion)
 - `:ZPack[!] delete [plugin]` - Remove a specific plugin, or all plugins with `!` (supports tab completion)
   - Deleting active plugins in your spec can result in errors in your current session. Restart Neovim to re-install them.
+- `:ZPack sync` - Bulk update + clean in one step (always force-applies; use `:ZPack update` without `!` for a preview). lazy.nvim parity for `:Lazy sync`
+- `:ZPack reload {plugin}` - Re-source a plugin (runs `deactivate`, clears `package.loaded`, re-runs config). lazy.nvim parity for `:Lazy reload`
 
 On Neovim 0.13+, several subcommands map to native `vim.pack` commands you can use interchangeably:
 
@@ -170,7 +172,10 @@ zpack might be for you if:
 
 As a thin layer, zpack does not provide:
 - UI dashboard for your plugins (see [Extensions](#extensions) for community solutions)
-- Advanced profiling, dev mode, change-detection, etc.
+- Advanced profiling, file-watch / auto-reload, change-detection, etc.
+  (`dev = true` rewrites a spec's source to a local checkout under
+  `setup({ dev = { path } })`; live file-watch is out of scope. `:ZPack
+  reload {plugin}` is a manual command, not an autocmd-driven reload.)
 
 If you're a lazy.nvim user, see [Migrating from lazy.nvim](docs/tips.md#migrating-from-lazynvim)
 

diff --git a/doc/zpack.txt b/doc/zpack.txt
@@ -148,6 +148,18 @@ command name is configurable via |zpack-setup-cmd_name| — a short name like
                 `:packdel! ++all` — though the native command also removes
                 any installed plugins absent from your spec.
 
+:ZPack sync     Bulk update + clean in one step (always force-applies; use
+                `:ZPack update` without `!` for a preview). lazy.nvim parity
+                for `:Lazy sync`.
+
+:ZPack reload {plugin}
+                Re-source a plugin: runs the plugin's `deactivate` hook (if
+                defined), drops its `package.loaded` modules, resets its
+                load state, and re-runs the lifecycle. Useful when iterating
+                on a plugin's code without restarting Neovim — typical for
+                authors using `dev = true`. lazy.nvim parity for
+                `:Lazy reload <plugin>`.
+
 ------------------------------------------------------------------------------
 4.3 CONFIGURATIONS                                     *zpack-configurations*
                                                        *zpack-setup-defaults*
@@ -243,6 +255,18 @@ performance     (table, optional)
                 Performance-related settings.
                   - `vim_loader`: Enable vim.loader caching. Default: `true`
 
+                                                              *zpack-setup-dev*
+dev             (table, optional)
+                lazy.nvim parity: control where `dev = true` spec entries
+                resolve to. When a spec sets `dev = true`, its source is
+                rewritten to `path .. '/' .. derived_name`.
+                  - `path`: Base directory for local plugin checkouts.
+                    Default: `'~/projects'`.
+                  - `fallback`: When the local directory is missing, fall
+                    through to the regular `[1]` / `src` / `url` / `dir`
+                    chain instead of using the dev path anyway.
+                    Default: `false`.
+
 ------------------------------------------------------------------------------
 4.6 HEALTH CHECK                                              *zpack-health*
 
@@ -304,7 +328,10 @@ zpack might be for you if:
 
 As a thin layer, zpack does not provide:
 - UI dashboard for your plugins (see |zpack-extensions|)
-- Advanced profiling, dev mode, change-detection, etc.
+- Advanced profiling, file-watch / auto-reload, change-detection, etc.
+  (`dev = true` rewrites a spec's source to a local checkout under
+  `setup({ dev = { path } })`; live file-watch is out of scope. `:ZPack
+  reload {plugin}` is a manual command, not an autocmd-driven reload.)
 
 If you're a lazy.nvim user, see |zpack-migrating-lazy|. If something you
 need isn't achievable natively or through zpack, please submit an issue
@@ -580,7 +607,11 @@ parent's lazy trigger fires.
       init = function(plugin) end,          -- Runs before load
       config = function(plugin, opts) end,  -- Runs after load
       -- config = true,                      -- Calls require(main).setup({})
-      build = string|function(plugin),      -- Build command/function
+      build = string|function(plugin)       -- Build step:
+            | (string|function(plugin))[]   --   ':<ex>' = ex-cmd; other = shell
+            | false,                        --   array runs steps in order
+                                            --   `false` opts out (lazy.nvim parity)
+      deactivate = function(plugin) end,    -- :ZPack reload teardown hook
 
       -- Lazy loading triggers (auto-sets lazy=true unless overridden)
       -- All triggers can also be functions receiving zpack.Plugin
@@ -596,6 +627,7 @@ parent's lazy trigger fires.
       -- Source control (version for `vim.pack.add`, string|vim.VersionRange)
       version = "main",                     -- Branch/tag/commit
       -- version = vim.version.range("1.*"), -- Or semver range
+      -- version = false,                    -- Opt out (lazy.nvim parity)
 
       -- Source control (lazy.nvim compat, mapped to version)
       sem_version = "^1.0.0",               -- lazy.nvim's version field
@@ -608,8 +640,18 @@ parent's lazy trigger fires.
       main = "module.name",                 -- Explicit main module
       module = false,                       -- Disable module-based lazy loading
 
+      -- lazy.nvim parity flags
+      pin = true,                           -- Exclude from :ZPack update bulk runs
+      optional = true,                      -- Only install if also referenced
+                                            --   non-optionally elsewhere
+      dev = true,                           -- Use local checkout under
+                                            --   setup({ dev = { path } })
+      specs = { ... },                      -- Companion plugin specs grouped
+                                            --   with this one (peers, not deps)
+
       -- Spec imports
-      import = "plugins.lsp",               -- Import specs from lua/{path}/
+      import = "plugins.lsp"                -- Module path string
+            | function() return {...} end,  -- Or function returning specs
     }
 <
 
@@ -805,12 +847,52 @@ module          (boolean, optional)
                 Default: true (module loading enabled)
 
                                                           *zpack-Spec.import*
-import          (string, optional)
+import          (string|function, optional)
                 Module path to import specs from (e.g., 'plugins' or
                 'plugins.lsp'). Imports all .lua files from lua/{path}/
                 and all subdirectories with init.lua (lua/{path}/*/init.lua).
                 Each file should return a spec or list of specs.
 
+                lazy.nvim parity: `import` also accepts a function. The
+                function is called inside pcall, and a table return value
+                is treated as a spec list to recurse into.
+
+                                                            *zpack-Spec.pin*
+pin             (boolean, optional)
+                lazy.nvim parity. When `true`, exclude this plugin from
+                bulk `:ZPack update` runs (still installed; just never
+                auto-updated). A single-name update `:ZPack update {name}`
+                still updates a pinned plugin (explicit beats policy).
+
+                                                       *zpack-Spec.optional*
+optional        (boolean, optional)
+                lazy.nvim parity. When `true`, only include this plugin
+                if some non-optional spec also references it (e.g. another
+                spec's `dependencies` list). An optional-only plugin is
+                silently dropped at merge time.
+
+                                                            *zpack-Spec.dev*
+dev             (boolean, optional)
+                lazy.nvim parity. When `true`, rewrite this spec's source
+                to a local checkout under |zpack-setup-dev|'s `path` (the
+                derived plugin name is appended). Useful for plugin authors
+                iterating locally without changing the spec for ship.
+
+                                                          *zpack-Spec.specs*
+specs           (zpack.Spec|zpack.Spec[], optional)
+                lazy.nvim parity. Companion plugin specs grouped with this
+                one. Unlike `dependencies`, these are peers (NOT loaded
+                before this plugin) — they walk through the normal import
+                path and become first-class registry entries.
+
+                                                     *zpack-Spec.deactivate*
+deactivate      (function(plugin), optional)
+                lazy.nvim parity. Teardown hook invoked by
+                `:ZPack reload {plugin}` before the plugin is re-sourced.
+                Use it to remove autocommands, keymaps, or watchers the
+                plugin installed at load time. A throw is caught and
+                surfaces as a warning; reload still proceeds.
+
 ==============================================================================
 8. PLUGIN REFERENCE                                *zpack-plugin-reference*
                                                               *zpack.Plugin*
@@ -820,6 +902,14 @@ The plugin data object passed to hooks and trigger functions:
     {
       spec = vim.pack.Spec,           -- The resolved vim.pack spec
       path = string,                  -- Absolute path to plugin directory
+      name = string,                  -- Resolved plugin name (alias for
+                                      -- spec.name, lazy.nvim parity)
+      dir = string,                   -- Plugin directory (alias for path,
+                                      -- lazy.nvim parity)
+      dependencies = string[],        -- Sorted list of resolved dependency
+                                      -- names (lazy.nvim parity)
+      main = string?,                 -- Detected main module name
+                                      -- (available after config resolves)
     }
 <
 
@@ -831,6 +921,23 @@ spec            (vim.pack.Spec)
 path            (string)
                 Absolute path to the plugin directory.
 
+                                                        *zpack.Plugin.name*
+name            (string)
+                Resolved plugin name. Alias for `spec.name`. Added for
+                lazy.nvim spec drop-in compatibility (LazyPlugin.name).
+
+                                                         *zpack.Plugin.dir*
+dir             (string)
+                Plugin directory. Alias for `path`. Added for lazy.nvim
+                spec drop-in compatibility (LazyPlugin.dir).
+
+                                                *zpack.Plugin.dependencies*
+dependencies    (string[])
+                Sorted list of resolved dependency names — the plugins
+                this entry depends on, derived from the resolved spec
+                tree. Added for lazy.nvim spec drop-in compatibility
+                (LazyPlugin.dependencies).
+
 ==============================================================================
 9. EVENTSPEC REFERENCE                            *zpack-eventspec-reference*
                                                        *zpack.EventSpec*
@@ -957,8 +1064,12 @@ version pinning           lazy.nvim's `version` field maps to zpack's
                           `sem_version`. See |zpack-example-version|.
 
                                                         *zpack-migration-dev*
-dev mode                  Use `src = vim.fn.expand('~/projects/my_plugin.nvim')`
-                          for local development.
+dev mode                  Set `dev = true` on a spec and configure
+                          `setup({ dev = { path = '~/projects' } })` —
+                          the source is rewritten to `<path>/<plugin-name>`.
+                          See |zpack-Spec.dev| and |zpack-setup-dev|.
+                          Live file-watch / auto-reload is out of scope;
+                          use `:ZPack reload {plugin}` to manually re-source.
 
                                                   *zpack-migration-profiling*
 profiling                 Use `nvim --startuptime startuptime.log`.

diff --git a/docs/spec.md b/docs/spec.md
@@ -25,7 +25,13 @@
   init = function(plugin) end,          -- Runs before plugin loads, useful for certain vim plugins
   config = function(plugin, opts) end,  -- Runs after plugin loads, receives resolved opts
   -- config = true,                      -- Calls require(main).setup({})
-  build = string|function(plugin),      -- Build command or function
+  build = string|function(plugin)       -- Build step:
+        | (string|function(plugin))[]   --   - ':<ex>' runs as an ex-command
+        | false,                        --   - other strings run via $SHELL in plugin dir
+                                        --   - functions receive the plugin
+                                        --   - arrays run each entry in order
+                                        --   - `false` opts out (lazy.nvim parity)
+  deactivate = function(plugin) end,    -- Teardown hook for :ZPack reload (lazy.nvim parity)
 
   -- Lazy loading triggers (auto-sets lazy=true unless overridden)
   -- All triggers can also be functions that receive zpack.Plugin and return the respective type
@@ -38,6 +44,7 @@
   -- Source control (version for `vim.pack.add`, string|vim.VersionRange)
   version = "main",                     -- Git branch, tag, or commit
   -- version = vim.version.range("1.*"), -- Or semver range via vim.version.range()
+  -- version = false,                    -- Opt out of versioning (lazy.nvim escape hatch)
 
   -- Source control (lazy.nvim compat, mapped to version)
   sem_version = "^1.0.0",               -- Semver string (corresponds to lazy.nvim spec's version), auto-wrapped to vim.version.range()
@@ -50,8 +57,15 @@
   main = "module.name",                 -- Explicit main module (auto-detected if not set)
   module = false,                       -- Disable module-based lazy loading for this plugin
 
+  -- lazy.nvim spec parity flags
+  pin = true,                           -- Exclude from :ZPack update bulk runs
+  optional = true,                      -- Only install if also referenced elsewhere non-optionally
+  dev = true,                           -- Use local checkout under setup({ dev = { path = '~/projects' } })
+  specs = { { 'companion/plugin' } },   -- Companion plugin specs grouped with this one
+
   -- Spec imports
   import = "plugins.lsp",               -- Import from lua/{path}/*.lua and lua/{path}/*/init.lua
+  -- import = function() return { ... } end, -- Or a function returning a spec list (lazy.nvim parity)
 }
 ```
 
@@ -63,6 +77,10 @@ The plugin data object passed to hooks and trigger functions:
 {
   spec = vim.pack.Spec,           -- The resolved vim.pack spec (name, src, version)
   path = string,                  -- Absolute path to the plugin directory
+  name = string,                  -- Resolved plugin name (alias for spec.name, lazy.nvim parity)
+  dir = string,                   -- Plugin directory (alias for path, lazy.nvim parity)
+  dependencies = string[],        -- Sorted list of resolved dependency names (lazy.nvim parity)
+  main = string?,                 -- Detected main module name (available after config)
 }
 ```
 

diff --git a/docs/tips.md b/docs/tips.md
@@ -4,7 +4,7 @@
 
 Most of your lazy.nvim plugin specs will work as-is with zpack. However, zpack follows `vim.pack` conventions over lazy.nvim conventions, and is missing a few advanced features:
 - **version pinning**: lazy.nvim's `version` field maps to zpack's `sem_version`. See [Spec Reference](spec.md) and [version pinning examples](examples.md#version-pinning-for-lazynvim-compatibility)
-- **dev mode**: Use `src = vim.fn.expand('~/projects/my_plugin.nvim')` for local development
+- **dev mode**: Set `dev = true` on a spec and configure `setup({ dev = { path = '~/projects' } })` — the source is rewritten to `<path>/<plugin-name>`. Live file-watch / auto-reload is out of scope; use `:ZPack reload {plugin}` to manually re-source. See [Spec Reference](spec.md) for `dev`/`deactivate`
 - **profiling**: Use `nvim --startuptime startuptime.log`. Also refer to example [Neovim Profiler script](https://gist.github.com/zuqini/35993710f81983fbfa6baca67bdb32ed)
 - **default lazy plugins**: lazy.nvim's community specs silently default top-level specs for utility libraries like `plenary.nvim` to `lazy = true`, even without lazy triggers or a lazy parent. zpack respects your specs as-written, so set `lazy = true` explicitly on such specs if you want the same default