feat: auto-expand dir field paths with vim.fn.expand()

This matches lazy.nvim behavior where ~ is expanded to home directory.

Also includes documentation improvements:
- Reorganized README to move import examples to dedicated section
- Changed "bells and whistles" to "frills" for clarity
- Removed first-person language ("my personal config" -> "example config")

Author: zuqini

README.md

@@ -159,7 +159,7 @@ As a thin layer, zpack does not provide:
 If you're a lazy.nvim user, see [Migrating from lazy.nvim](#migrating-from-lazynvim)
 
 ## Examples
-For more examples, refer to my personal config:
+For more examples, refer to example config:
 - [zpack installation and setup](https://github.com/zuqini/nvim/blob/main/init.lua)
 - [plugins directory structure](https://github.com/zuqini/nvim/tree/main/lua/plugins)
 
@@ -366,7 +366,7 @@ return {
   -- Plugin source (provide exactly one)
   [1] = "user/repo",                    -- Plugin short name. Expands to https://github.com/{user/repo}
   src = "https://...",                  -- Custom git URL or local path
-  dir = "/path/to/plugin",              -- Local plugin directory (lazy.nvim compat, mapped to src)
+  dir = "/path/to/plugin",              -- Local plugin directory (lazy.nvim compat, ~ expanded, mapped to src)
   url = "https://...",                  -- Custom git URL (lazy.nvim compat, mapped to src)
 
   -- Dependencies
@@ -454,7 +454,7 @@ The plugin data object passed to hooks and trigger functions:
 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 [Version Pinning](#version-pinning-for-lazynvim-compatibility)
 - **dev mode**: Use `src = vim.fn.expand('~/projects/my_plugin.nvim')` for local development
-- **profiling**: Use `nvim --startuptime startuptime.log`. Also see my [Neovim Profiler script](https://gist.github.com/zuqini/35993710f81983fbfa6baca67bdb32ed)
+- **profiling**: Use `nvim --startuptime startuptime.log`. Also refer to example [Neovim Profiler script](https://gist.github.com/zuqini/35993710f81983fbfa6baca67bdb32ed)
 
 ## Acknowledgements
 

doc/zpack.txt

@@ -263,7 +263,7 @@ through zpack, please submit an issue or PR!
 ==============================================================================
 6. EXAMPLES                                                   *zpack-examples*
 
-For more examples, refer to my personal config:
+For more examples, refer to example config:
 - zpack installation and setup:
   https://github.com/zuqini/nvim/blob/main/init.lua
 - plugins directory structure:
@@ -502,7 +502,7 @@ parent's lazy trigger fires.
       -- Plugin source (provide exactly one)
       [1] = "user/repo",                    -- Short name (github.com/...)
       src = "https://...",                  -- Custom git URL or local path
-      dir = "/path/to/plugin",              -- Local path (lazy.nvim compat)
+      dir = "/path/to/plugin",              -- Local path (lazy.nvim compat, ~ expanded)
       url = "https://...",                  -- Git URL (lazy.nvim compat)
 
       -- Dependencies
@@ -569,8 +569,9 @@ src             (string, optional)
                                                              *zpack-Spec.dir*
 dir             (string, optional)
                 Local plugin directory path. For lazy.nvim compatibility.
-                Mapped to `src` internally. Provide exactly one of:
-                [1], src, dir, or url.
+                Paths are automatically expanded (e.g., `~` expands to home
+                directory). Mapped to `src` internally. Provide exactly one
+                of: [1], src, dir, or url.
 
                                                              *zpack-Spec.url*
 url             (string, optional)

lua/zpack/import.lua

@@ -27,7 +27,7 @@ local normalize_source = function(spec)
   elseif spec.url then
     return spec.url
   elseif spec.dir then
-    return spec.dir
+    return vim.fn.expand(spec.dir)
   else
     return nil, "spec must provide one of: [1], src, dir, or url"
   end

tests/setup_test.lua

@@ -184,5 +184,22 @@ return function()
 
       helpers.cleanup_test_env()
     end)
+
+    helpers.test("dir field expands ~ to home directory", function()
+      helpers.setup_test_env()
+      local state = require('zpack.state')
+
+      require('zpack').setup({
+        spec = {
+          { dir = '~/projects/my-plugin' },
+        },
+        defaults = { confirm = false },
+      })
+
+      local expected_src = vim.fn.expand('~/projects/my-plugin')
+      helpers.assert_not_nil(state.spec_registry[expected_src], "dir should expand ~ to home directory")
+
+      helpers.cleanup_test_env()
+    end)
   end)
 end