Merge pull request #1 from anodynos/feat/UP-002-readme-hollywood

docs: README Hollywood refresh + Polar funding (UP-002)
GitOrigin-RevId: ee3ced87dac35f5d2c3100f9ad9bdb715e5ce2f6

Author: anodynos

.github/FUNDING.yml

@@ -1,2 +1,3 @@
 github: anodynos
+polar: anodynos
 tidelift: npm/upath

.gitignore

@@ -5,3 +5,4 @@ build
 DRAFT
 *.tsbuildinfo
 coverage
+.claude/worktrees/

.husky/pre-commit

@@ -1 +1,9 @@
-npx lint-staged
+# If lint-staged not in PATH (no local node_modules), use main worktree's
+if ! command -v lint-staged >/dev/null 2>&1; then
+  MAIN_WT=$(git worktree list --porcelain | head -1 | sed 's/worktree //')
+  if [ -d "$MAIN_WT/node_modules/.bin" ]; then
+    export PATH="$MAIN_WT/node_modules/.bin:$PATH"
+  fi
+fi
+
+lint-staged

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [3.0.6] - 2026-04-09
+
+### Added
+
+- **Polar.sh funding** -- added to `.github/FUNDING.yml` and `package.json` alongside existing GitHub Sponsors and Tidelift.
+- **"Who Uses upath" section** in README -- trust signals with notable dependents (Chokidar, Nuxt, 1,300+ npm packages).
+- **Architecture section** in README -- explains the dynamic proxy pattern and how upath stays in sync with Node.js.
+
+### Changed
+
+- **README revamped** -- pain-first API docs showing `path` vs `upath` behavior side-by-side, inspired by the v2-era docs. Every extra function now explains _why_ it exists (what `path` does wrong).
+- **Deterministic `docs/API.md` generation** -- test files are now sorted by name before the doc reporter processes them, eliminating spurious diffs caused by Jest's non-deterministic parallel execution order.
+
+### Fixed
+
+- **Pre-commit hook now works in git worktrees without `node_modules`** -- the hook falls back to the main worktree's `node_modules/.bin` when lint-staged isn't found locally.
+
+## [3.0.1] - [3.0.5]
+
+Patch releases for CI/CD setup (Copybara bidirectional sync, Trusted Publishing OIDC), build fixes, and internal tooling. No user-facing API changes.
+
 ## [3.0.0] - 2026-04-05
 
 ### Breaking Changes
@@ -31,4 +52,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - Build toolchain changed to tsup (dual CJS + ESM output).
 - Test framework changed to Jest with ts-jest.
 
+[3.0.6]: https://github.com/anodynos/upath/compare/v3.0.5...v3.0.6
 [3.0.0]: https://github.com/anodynos/upath/releases/tag/v3.0.0

docs/API.md

@@ -2,9 +2,7 @@
 
 > Auto-generated from test results by `doc-reporter.ts`. Do not edit manually.
 >
-> **Note:** Node.js compatibility tests (200+ vectors in [`node-compat.test.ts`](../src/__tests__/node-compat.test.ts))
-> are excluded from this document for brevity. Those tests verify that every proxied `path` function produces identical
-> results to Node.js built-in `path`.
+> **Note:** Node.js compatibility tests (200+ vectors in [`node-compat.test.ts`](../src/__tests__/node-compat.test.ts)) are excluded from this document for brevity. Those tests verify that every proxied `path` function produces identical results to Node.js built-in `path`.
 
 ## `upath.addExt(filename, ext)`
 
@@ -128,50 +126,6 @@
 | `"fileWith/defaultExt.longExt", 'js', ['min', '.dev'], 8`  | `"fileWith/defaultExt.longExt"`     |
 | `"fileWith/defaultExt.longRext", 'js', ['min', '.dev'], 8` | `"fileWith/defaultExt.longRext.js"` |
 
-## `upath.normalize(path)`
-
-| Input                             | Output                     |
-| --------------------------------- | -------------------------- |
-| `"c:/windows/nodejs/path"`        | `"c:/windows/nodejs/path"` |
-| `"c:/windows/../nodejs/path"`     | `"c:/nodejs/path"`         |
-| `"c:\\windows\\nodejs\\path"`     | `"c:/windows/nodejs/path"` |
-| `"c:\\windows\\..\\nodejs\\path"` | `"c:/nodejs/path"`         |
-| `"/windows\\unix/mixed"`          | `"/windows/unix/mixed"`    |
-| `"\\windows//unix/mixed"`         | `"/windows/unix/mixed"`    |
-| `"\\windows\\..\\unix/mixed/"`    | `"/unix/mixed/"`           |
-
-## `upath.join(paths...)`
-
-| Input                                | Output                |
-| ------------------------------------ | --------------------- |
-| `["some/nodejs/deep","../path"]`     | `"some/nodejs/path"`  |
-| `["some/nodejs\\windows","../path"]` | `"some/nodejs/path"`  |
-| `["some\\windows\\only","..\\path"]` | `"some/windows/path"` |
-
-## `upath.toUnix(path)`
-
-| Input                               | Output                       |
-| ----------------------------------- | ---------------------------- |
-| `".//windows\\//unix/\\/mixed////"` | `"./windows/unix/mixed/"`    |
-| `"..///windows\\..\\\\unix/mixed"`  | `"../windows/../unix/mixed"` |
-| `""`                                | `""`                         |
-| `"/"`                               | `"/"`                        |
-| `"\\\\server\\share"`               | `"//server/share"`           |
-| `"already/forward/slashes"`         | `"already/forward/slashes"`  |
-| `"\\"`                              | `"/"`                        |
-| `"////multiple///slashes"`          | `"//multiple/slashes"`       |
-| `"mixed\\back//and///slashes"`      | `"mixed/back/and/slashes"`   |
-| `"a\\b\\c"`                         | `"a/b/c"`                    |
-| `"C:\\Users\\test"`                 | `"C:/Users/test"`            |
-
-## `upath.isAbsolute(path) — backslash normalization`
-
-| Input                 | Output                         |
-| --------------------- | ------------------------------ |
-| `"\\foo"`             | `true (backslash normalized)`  |
-| `"\\\\server\\share"` | `true (backslash normalized)`  |
-| `"foo\\bar"`          | `false (backslash normalized)` |
-
 ## `upath.normalizeSafe(path)`
 
 ### equal to path.normalize
@@ -246,3 +200,47 @@
 | `["//./c:/temp/file","../path"]`              | `"//./c:/temp/path"`      |
 | `["",""]`                                     | `"."`                     |
 | `["./foo","","bar"]`                          | `"./foo/bar"`             |
+
+## `upath.normalize(path)`
+
+| Input                             | Output                     |
+| --------------------------------- | -------------------------- |
+| `"c:/windows/nodejs/path"`        | `"c:/windows/nodejs/path"` |
+| `"c:/windows/../nodejs/path"`     | `"c:/nodejs/path"`         |
+| `"c:\\windows\\nodejs\\path"`     | `"c:/windows/nodejs/path"` |
+| `"c:\\windows\\..\\nodejs\\path"` | `"c:/nodejs/path"`         |
+| `"/windows\\unix/mixed"`          | `"/windows/unix/mixed"`    |
+| `"\\windows//unix/mixed"`         | `"/windows/unix/mixed"`    |
+| `"\\windows\\..\\unix/mixed/"`    | `"/unix/mixed/"`           |
+
+## `upath.join(paths...)`
+
+| Input                                | Output                |
+| ------------------------------------ | --------------------- |
+| `["some/nodejs/deep","../path"]`     | `"some/nodejs/path"`  |
+| `["some/nodejs\\windows","../path"]` | `"some/nodejs/path"`  |
+| `["some\\windows\\only","..\\path"]` | `"some/windows/path"` |
+
+## `upath.toUnix(path)`
+
+| Input                               | Output                       |
+| ----------------------------------- | ---------------------------- |
+| `".//windows\\//unix/\\/mixed////"` | `"./windows/unix/mixed/"`    |
+| `"..///windows\\..\\\\unix/mixed"`  | `"../windows/../unix/mixed"` |
+| `""`                                | `""`                         |
+| `"/"`                               | `"/"`                        |
+| `"\\\\server\\share"`               | `"//server/share"`           |
+| `"already/forward/slashes"`         | `"already/forward/slashes"`  |
+| `"\\"`                              | `"/"`                        |
+| `"////multiple///slashes"`          | `"//multiple/slashes"`       |
+| `"mixed\\back//and///slashes"`      | `"mixed/back/and/slashes"`   |
+| `"a\\b\\c"`                         | `"a/b/c"`                    |
+| `"C:\\Users\\test"`                 | `"C:/Users/test"`            |
+
+## `upath.isAbsolute(path) — backslash normalization`
+
+| Input                 | Output                         |
+| --------------------- | ------------------------------ |
+| `"\\foo"`             | `true (backslash normalized)`  |
+| `"\\\\server\\share"` | `true (backslash normalized)`  |
+| `"foo\\bar"`          | `false (backslash normalized)` |

package.json

@@ -1,7 +1,7 @@
 {
   "name": "upath",
   "description": "A drop-in replacement / proxy to Node.js path, replacing \\\\ with / for all results & adding file extension functions.",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "homepage": "https://github.com/anodynos/upath/",
   "author": {
     "name": "Angelos Pikoulas",
@@ -13,6 +13,10 @@
       "type": "github",
       "url": "https://github.com/sponsors/anodynos"
     },
+    {
+      "type": "polar",
+      "url": "https://polar.sh/anodynos"
+    },
     {
       "type": "tidelift",
       "url": "https://tidelift.com/subscription/pkg/npm-upath"