WSL DrvFs install fails on .bin symlink (EPERM); docs/fallback needed

[stackbilt-admin]

Summary

Installing @stackbilt/cli on WSL DrvFs workspaces can fail with EPERM on .bin symlink creation.

Repro

Environment:

• WSL
• Repo path on DrvFs mount: /mnt/d/...
• npm v10 (Node v22)

Command:

npm install --save-dev @stackbilt/cli@0.16.0

Observed error:

EPERM: operation not permitted, symlink '../@stackbilt/cli/dist/bin.js' -> '/mnt/.../node_modules/.bin/charter'

Workaround

This succeeds:

npm install --save-dev @stackbilt/cli@0.16.0 --no-bin-links

Requested Improvement

• Add first-class docs for WSL/DrvFs install mode (--no-bin-links), and
• Consider detecting this failure pattern and printing an actionable fallback hint.

This would remove friction for non-Node repos that add Charter as local governance tooling.

[stackbilt-admin]

Fixed in c8a94f2. The Install section now has a WSL/DrvFs table that distinguishes the two error patterns:

• npm EPERM on .bin/charter → npm install --save-dev @stackbilt/cli --no-bin-links, then invoke via npx --no-install charter or ./node_modules/.bin/charter
• pnpm EACCES on atomic rename → pnpm add --force or move to a Linux-native path

Also added a non-Node repo quickstart section above it (see #185) that leads with --no-bin-links as the recommended install path for non-Node repos, which preempts the EPERM entirely for that audience.

[stackbilt-admin]

Docs update is shipped and matches this issue's requested fallback.

Verified on 2026-05-24 in main:

• README.md now has a dedicated WSL / DrvFs installs section.
• It documents the exact fallback command: npm install --save-dev @stackbilt/cli --no-bin-links.
• It also documents invocation without symlinked bins via npx --no-install charter / direct bin path guidance.

Evidence lines:

• README.md:60
• README.md:66

Marking resolved and closing.

[stackbilt-admin]

Closing as completed by the 2026-05-23 docs update.