Skip to content

Commit c8a94f2

Browse files
Kurt Overmierclaude
andcommitted
docs: add non-Node repo quickstart and WSL DrvFs install table (#184 #185)
Addresses two friction points reported by the coex team onboarding Charter into a C++ repo: - Non-Node quickstart: shows --no-bin-links install, npx --no-install invocation, and ./node_modules/.bin/charter as fallback. Adds a package.json scripts example for governance:check / governance:doctor. - WSL/DrvFs table: distinguishes the npm EPERM symlink error from the pnpm EACCES rename error with a fix for each. - Drops the stale @0.12.0 deprecation notice (superseded by 1.0.0). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 0ca0ebc commit c8a94f2

1 file changed

Lines changed: 34 additions & 2 deletions

File tree

README.md

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,41 @@ npm install --save-dev @stackbilt/cli
3232

3333
For pnpm workspaces: `pnpm add -Dw @stackbilt/cli`. For global install: `npm install -g @stackbilt/cli`.
3434

35-
> If you installed `@stackbilt/cli@0.12.0`, upgrade to `0.12.1` or later. `0.12.0` was deprecated due to invalid published `workspace:` dependency specifiers for external consumers.
35+
### Non-Node repos (C++, Go, Rust, etc.)
3636

37-
> **WSL2 note:** If your project lives on the Windows filesystem (`/mnt/c/...`), pnpm may fail with `EACCES` permission errors due to WSL2/NTFS cross-filesystem limitations with atomic renames. Use `pnpm add --force` to work around this, or move your project to a Linux-native path (e.g., `~/projects/`) for best performance.
37+
Charter works as a local governance tool in any repo — Node is not required as your primary build system. Add it as a dev dependency and invoke it without a global install:
38+
39+
```bash
40+
# Install (WSL-safe mode if you hit symlink errors — see below)
41+
npm install --save-dev @stackbilt/cli --no-bin-links
42+
43+
# Run via npx (resolves from local node_modules, no global install needed)
44+
npx --no-install charter bootstrap --yes
45+
npx --no-install charter doctor --adf-only
46+
47+
# Or invoke directly
48+
./node_modules/.bin/charter doctor --adf-only
49+
```
50+
51+
Add to your `package.json` scripts for convenience:
52+
53+
```json
54+
"scripts": {
55+
"governance:check": "charter audit --ci",
56+
"governance:doctor": "charter doctor --adf-only"
57+
}
58+
```
59+
60+
### WSL / DrvFs installs
61+
62+
Two distinct issues can appear when the repo lives on a Windows-mounted filesystem (`/mnt/c/...`, `/mnt/d/...`):
63+
64+
| Symptom | Package manager | Fix |
65+
|---------|----------------|-----|
66+
| `EPERM: operation not permitted, symlink` on `.bin/charter` | npm | `npm install --save-dev @stackbilt/cli --no-bin-links` — skips symlink creation; use `npx --no-install charter` or `./node_modules/.bin/charter` to invoke |
67+
| `EACCES` on atomic rename during install | pnpm | `pnpm add --force` or move the repo to a Linux-native path (`~/projects/`) |
68+
69+
Both flags are safe for CI environments where the filesystem is Linux-native — the workarounds only matter locally on DrvFs mounts.
3870

3971
## AI agent governance with ADF
4072

0 commit comments

Comments
 (0)