zuqini · Nov 2, 2026 · Nov 2, 2026
diff --git a/README.md b/README.md
@@ -72,11 +72,11 @@ zpack provides a single user command, `:ZPack`, with subcommands. Rename via [`c
 | --- | --- |
 | `:ZPack[!] update [plugin]` | Update all plugins, or one; `!` skips the confirm buffer |
 | `:ZPack[!] restore [plugin]` | Restore plugins to the lockfile state; `!` skips the confirm buffer |
-| `:ZPack clean` | Remove plugins no longer in your spec |
+| `:ZPack[!] clean` | Remove plugins no longer in your spec, after listing them and asking; `!` doesn't ask |
 | `:ZPack[!] build [plugin]` | Run a plugin's build hook; `!` runs every plugin's build hook |
 | `:ZPack[!] load [plugin]` | Load an unloaded plugin; `!` loads all unloaded plugins |
 | `:ZPack[!] delete [plugin]` | Remove a plugin; `!` removes all plugins |
-| `:ZPack sync` | Bulk update + clean (lazy.nvim parity) |
+| `:ZPack[!] sync` | Bulk update + clean (lazy.nvim parity); `!` doesn't ask before deleting |
 | `:ZPack reload {plugin}` | Re-source a plugin (lazy.nvim parity) |
 
 
@@ -108,7 +108,7 @@ Plugin-level settings always take precedence over `defaults`.
 require('zpack').setup()
 
 -- or import from a custom path `./lua/a/b/plugins.lua` or `./lua/a/b/plugins/`
-require('zpack').setup({ { import = 'a.b.plugins' } })
+require('zpack').setup('a.b.plugins') -- or setup({ spec = 'a.b.plugins' }), or a list with { import = 'a.b.plugins' }
 
 -- or add your specs inline in setup
 require('zpack').setup({
@@ -167,7 +167,7 @@ See **[Spec Reference](docs/spec.md)** for the full spec definition, including `
 
 ## Tips & Migration
 
-See **[Tips & Migration](docs/tips.md)** for lazy.nvim migration guide and compatibility notes for popular plugins (Snacks.nvim dashboard, noice.nvim, etc.).
+See **[Tips & Migration](docs/tips.md)** for lazy.nvim migration guide and compatibility notes for popular plugins (Snacks.nvim dashboard, noice.nvim, etc.). Coming from 2.x, read [Upgrading to 3.0](docs/tips.md#upgrading-to-30).
 
 ## Public API
 

diff --git a/doc/zpack.txt b/doc/zpack.txt
diff --git a/docs/examples.md b/docs/examples.md
@@ -85,7 +85,7 @@ return {
 
 -- Or using EventSpec for multiple patterns
 return {
-  'polyglot-plugin',
+  'user/polyglot-plugin',
   event = {
     event = 'BufReadPre',
     pattern = { '*.lua', '*.rs' },
@@ -108,18 +108,18 @@ return {
 Plugins sharing a filetype load together in priority order and re-trigger these events once, after the last of them:
 
 - A plugin's `config` doesn't see `ftplugin` or `BufReadPre`/`BufReadPost` handler effects from others in the group, even with `dependencies` declared. Read such values from a `FileType` handler or the plugin's own `ftplugin` instead.
-- If several plugins ship an `ftplugin` guarded by `b:did_ftplugin`, the lowest-priority plugin wins.
+- If several plugins ship an `ftplugin` guarded by `b:did_ftplugin` that don't set `b:undo_ftplugin`, the lowest-priority plugin wins.
 - If a plugin's `config` loads another buffer of that filetype, `FileType` handlers of plugins still pending in the group miss that buffer. Declaring the pending plugin as a dependency avoids this.
 - Priority doesn't order different `ft` patterns, such as a literal and a glob: each loads when its own pattern's turn comes.
-- A plugin with `event = 'FileType'` between them in priority order splits the group if its pattern can match that filetype, at the cost of one extra re-trigger.
+- A plugin with `event = 'FileType'` between them in priority order splits the group, whatever its pattern, and each part re-triggers.
 
 #### Conditional Loading
 
 Use `enabled` to skip `vim.pack.add` entirely, or `cond` to conditionally load after calling `vim.pack.add`:
 
 ```lua
 return {
-  'project-specific-plugin',
+  'user/project-specific-plugin',
   enabled = vim.fn.has('linux') == 1, -- skip installation
   cond = function() return vim.fn.filereadable('.project-marker') == 1 end, -- skip loading
   opts = {},

diff --git a/docs/spec.md b/docs/spec.md
@@ -21,7 +21,7 @@
 
   -- Loading control
   enabled = true|false|function,        -- Enable/disable plugin
-  cond = true|false|function(plugin),   -- Condition to load plugin (on an `import`: whether to follow it; receives no plugin, or only its `name`, `spec`, `path` and `dir` if the spec has a source)
+  cond = true|false|function(plugin),   -- Condition to load plugin (on an `import`: whether to follow it, and it receives no plugin)
   lazy = true|false,                    -- Force eager loading when false (auto-detected)
   priority = 50,                        -- Load priority (higher = earlier, default: 50). Doesn't order different `ft` patterns.
 
@@ -48,7 +48,7 @@
   event = string|string[]|zpack.EventSpec|(string|zpack.EventSpec)[]|function(plugin, list), -- Autocommand event(s). Supports 'VeryLazy' and inline patterns: "BufReadPre *.lua". zpack auto-emits `User VeryLazy` once on UIEnter so user-config `autocmd User VeryLazy` hooks fire.
   pattern = string|string[],            -- Global fallback pattern(s) for all events
   cmd = string|string[]|function(plugin, list), -- Command(s) to create; tab-completion on the command also triggers the load
-  keys = string|string[]|zpack.KeySpec|zpack.KeySpec[]|function(plugin, list), -- Keymap(s) to create
+  keys = string|string[]|zpack.KeySpec|zpack.KeySpec[]|function(plugin, list), -- Keymap(s) to create. A table of only strings is a list of keys, so `{ lhs, 'dd' }` is two keys: nest it or add a field to make it one
   ft = string|string[]|function(plugin, list), -- FileType(s) to lazy load on. Plugins sharing a filetype load together and re-trigger FileType once, after the last of them.
 
   -- Source control (version for `vim.pack.add`, string|vim.VersionRange)