Problem: LuaLS struggles with the generics used in Nvim's runtime,
requiring broad diagnostic suppressions. Indexing is also slow.

Solution: Use EmmyLua for type checks in the build and CI. It offers
more sophisticated type checking, substantially better support for
generics, and much better flow analysis.

Correct the affected annotations. Use `@internal`, supported directly by
EmmyLua, instead of `@nodoc` for shared internal declarations, and
support it in the help parser.

AI-assisted

Problem:
Directory listing entries cannot be customized (filtered, reordered).
Listings are read by a BufReadCmd, which suppresses BufReadPost, so they
are the only buffers with no post-read event to hook.

Solution:
Introduce a post-render User autocmd `DirReadPost`, marking the dir
buffer writable for the duration and before the cursor is placed, so
handlers can sort or filter it with ordinary commands. Document common
recipes

Problem:  An error raised after the list handler ran (e.g. while
          rendering) unwinds through the pcall around provider.list()
          and is routed back into the now no-op handler: silently
          discarded.
Solution: Re-raise the error when the handler has already run.

Problem:  A failed initial directory listing discards the listing state:
          the user is left in an empty modifiable non-listing buffer, and
          the BufEnter autocmd retries the failing open, repeating the
          error on every re-entry.
Solution: Render the failure as an empty listing with state and handlers
          intact: the error is reported once and "R" or :edit retries the
          listing. Keep the error on the listing state so a failed
          listing is distinguishable from an empty one; the next list
          clears it.

Problem:
The core behaviors of `nvim.dir` cannot be reused by consumers
such as the archive plugin, ssh browser, etc.

Solution:
- Define a basic "provider" shape.
- Extract the filesystem provider.

Problem:
Third-party directory browsers do not have a documented way to take over local
directory buffers from nvim.dir.

Solution:
Document deleting the nvim.dir augroup and handling FileType directory as the
after-startup handoff, and avoid installing the built-in buffer-local "-" mapping
when "-" is already mapped.

Problem:
`vim.filetype.match()` needs a cheap way to recognize directory buffers
without doing filesystem stat work.

Solution:
Ensure full buffer names for directories end in a trailing slash. Now
directory buffers can proceed through the normal 'filetype' path.

Note side-effects: session and ShaDa buffer-list restore behavior must
be compatible, so those + corresponding tests must be updated.