impeccable 3.2.1 → 3.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable CLI
2
2
 
3
- Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 46 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 58 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
56
56
 
57
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
58
58
 
59
- 46 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 58 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
60
60
 
61
61
  ## Exit Codes
62
62
 
package/README.npm.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable CLI
2
2
 
3
- Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 46 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 58 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
56
56
 
57
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
58
58
 
59
- 46 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 58 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
60
60
 
61
61
  ## Exit Codes
62
62
 
package/README.repo.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable
2
2
 
3
- Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 46 deterministic detector rules for AI-generated frontend design.
3
+ Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 58 deterministic detector rules for AI-generated frontend design.
4
4
 
5
5
  > **Quick start:** From your project root, run `npx impeccable install`, then run `/impeccable init` inside your AI coding tool. Full docs: [impeccable.style](https://impeccable.style).
6
6
 
@@ -13,7 +13,7 @@ Every model trained on the same SaaS templates. Skip the guidance and you get th
13
13
  Impeccable adds:
14
14
  - **One setup flow.** `/impeccable init` writes `PRODUCT.md` and offers `DESIGN.md`, so later commands know the audience, brand/product lane, voice, anti-references, colors, type, and components.
15
15
  - **23 commands.** A shared design vocabulary with your AI: `polish`, `audit`, `critique`, `distill`, `animate`, `bolder`, `quieter`, and more.
16
- - **46 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
16
+ - **58 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
17
17
 
18
18
  ## What's Included
19
19
 
@@ -103,7 +103,7 @@ From the root of your project, run:
103
103
  npx impeccable install
104
104
  ```
105
105
 
106
- This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, and Codex, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, and every other supported tool. Reload your harness afterward.
106
+ This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, `~/.grok`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor,grok` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, Codex, GitHub Copilot, and Grok Build, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, and every other supported tool. Reload your harness afterward.
107
107
 
108
108
  To refresh an existing install, run:
109
109
 
@@ -111,7 +111,7 @@ To refresh an existing install, run:
111
111
  npx impeccable update
112
112
  ```
113
113
 
114
- Codex users should open `/hooks` after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change `.codex/hooks.json` can require approval again.
114
+ Codex users should open `/hooks` after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change `.codex/hooks.json` can require approval again. Grok Build users need project folder trust (`/hooks-trust` or launch with `--trust`) before `.grok/hooks/` scripts run.
115
115
 
116
116
  ### Option 2: Git Submodule
117
117
 
@@ -124,7 +124,7 @@ git add .gitmodules .impeccable .claude .cursor
124
124
  git commit -m "Add Impeccable skills"
125
125
  ```
126
126
 
127
- Use the providers your project needs, for example `claude`, `cursor`, `gemini`, `codex`, `github`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, or `rovo-dev`. The command links individual skill folders from `.impeccable/dist/universal/` and leaves existing real skill directories untouched unless you pass `--force`.
127
+ Use the providers your project needs, for example `claude`, `cursor`, `gemini`, `codex`, `github`, `grok`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, `rovo-dev`, or `vibe`. The command links individual skill folders from `.impeccable/dist/universal/` and leaves existing real skill directories untouched unless you pass `--force`.
128
128
 
129
129
  To update later:
130
130
 
@@ -144,10 +144,10 @@ npx impeccable link --source=.impeccable --providers=claude,cursor
144
144
 
145
145
  **Grok Build:**
146
146
  ```bash
147
- grok plugin install pbakaus/impeccable --trust
147
+ grok plugin install pbakaus/impeccable#plugin --trust
148
148
  ```
149
149
 
150
- > Grok Build only. Then run `/impeccable init` in a Grok session.
150
+ > Grok Build only. The `#plugin` suffix installs the slim plugin package (skills, agents, and hooks) instead of the full monorepo. Then run `/impeccable init` in a Grok session. Project-scoped installs via `npx impeccable install --providers=grok` also work and write `.grok/skills/` plus `.grok/hooks/impeccable.json`.
151
151
 
152
152
  ### Option 4: Download from Website
153
153
 
@@ -250,6 +250,26 @@ cp -r dist/qoder/.qoder your-project/
250
250
  cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/
251
251
  ```
252
252
 
253
+ **Mistral Vibe:**
254
+ ```bash
255
+ # Project-specific
256
+ cp -r dist/vibe/.vibe your-project/
257
+
258
+ # Or global (applies to all projects)
259
+ cp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/
260
+ ```
261
+
262
+ **Grok Build:**
263
+ ```bash
264
+ # Project-specific
265
+ cp -r dist/grok/.grok your-project/
266
+
267
+ # Or global (applies to all projects)
268
+ cp -r dist/grok/.grok/skills/* ~/.grok/skills/
269
+ ```
270
+
271
+ > Prefer `npx impeccable install --providers=grok` or `grok plugin install pbakaus/impeccable#plugin --trust` so the design hook installs too. Project hooks need `/hooks-trust` (or `--trust`) once per folder.
272
+
253
273
  ## Usage
254
274
 
255
275
  Once installed, every command runs through the single `/impeccable` skill:
@@ -316,7 +336,7 @@ If an ephemeral file (a screenshot, `config.local.json`) was committed before yo
316
336
 
317
337
  ## Design hook
318
338
 
319
- On Claude Code, GitHub Copilot, Codex, and Cursor, `npx impeccable install` and `npx impeccable update` install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, and Codex surface findings after the edit. Cursor blocks bad proposed writes before they land.
339
+ On Claude Code, GitHub Copilot, Codex, Cursor, and Grok Build, `npx impeccable install` and `npx impeccable update` install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, Codex, and Grok Build surface findings after the edit (and run a deeper pass on Stop where supported). Cursor blocks bad proposed writes before they land.
320
340
 
321
341
  Installed hook surfaces:
322
342
 
@@ -357,7 +377,7 @@ npx impeccable ignores add-file "src/legacy/**"
357
377
  npx impeccable ignores add-value overused-font Inter --reason "Brand font"
358
378
  ```
359
379
 
360
- The detector catches 46 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
380
+ The detector catches 49 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
361
381
 
362
382
  By default, `detect` respects the same `.impeccable/config.json` and `.impeccable/config.local.json` detector config as the design hook: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. Hook lifecycle settings such as `hook.enabled` only affect automatic hook execution.
363
383
 
@@ -379,6 +399,7 @@ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/do
379
399
  - [Trae](https://trae.ai)
380
400
  - [Rovo Dev](https://www.atlassian.com/software/rovo)
381
401
  - [Qoder](https://qoder.com)
402
+ - [Mistral Vibe](https://docs.mistral.ai/vibe/code/overview)
382
403
 
383
404
  ## Community & Ecosystem
384
405
 
@@ -78,6 +78,20 @@ function parseScope(args, { allowAll = false } = {}) {
78
78
  return { local, all, rest };
79
79
  }
80
80
 
81
+ // An empty glob used to be dropped by filter(Boolean), so `--file=` reported
82
+ // success and wrote an entry with no files: the user asked to scope a rule to one
83
+ // file and silently got the project-wide suppression instead. Refuse it.
84
+ function requireGlob(raw, flag) {
85
+ const glob = String(raw ?? '').trim();
86
+ if (!glob) throw new Error(`${flag} requires a non-empty glob`);
87
+ // A following flag is not a glob. `--file --reason "why"` consumed `--reason`
88
+ // as the scope and left the reason text to fold into the value, storing
89
+ // value="* why" files=["--reason"] and reporting success. Same silent-no-op
90
+ // class as an unknown flag folding into the value; refuse it the same way.
91
+ if (glob.startsWith('--')) throw new Error(`${flag} requires a glob, got the flag ${glob}`);
92
+ return glob;
93
+ }
94
+
81
95
  function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
82
96
  const positionals = [];
83
97
  const files = [];
@@ -93,11 +107,11 @@ function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
93
107
  reason = arg.slice('--reason='.length).trim();
94
108
  } else if (arg === '--file' || arg === '--files') {
95
109
  if (i + 1 >= args.length) throw new Error(`${arg} requires a glob`);
96
- files.push(String(args[++i]).trim());
110
+ files.push(requireGlob(args[++i], arg));
97
111
  } else if (arg.startsWith('--file=')) {
98
- files.push(arg.slice('--file='.length).trim());
112
+ files.push(requireGlob(arg.slice('--file='.length), '--file'));
99
113
  } else if (arg.startsWith('--files=')) {
100
- files.push(arg.slice('--files='.length).trim());
114
+ files.push(requireGlob(arg.slice('--files='.length), '--files'));
101
115
  } else if (arg.startsWith('--')) {
102
116
  throw new Error(`Unknown add-value flag: ${arg}`);
103
117
  } else {
@@ -108,7 +122,9 @@ function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
108
122
  const [rule, ...valueParts] = positionals;
109
123
  const value = normalizeIgnoreValue(valueParts.join(' '));
110
124
  if (!rule || !value) throw new Error('Pass a rule id and value, e.g. impeccable ignores add-value overused-font Inter');
111
- const scopedFiles = Array.from(new Set(files.filter(Boolean)));
125
+ // Sorted: the dedup key compares the files array, so an unsorted scope made
126
+ // `--file b.css --file a.css` a different entry from `--file a.css --file b.css`.
127
+ const scopedFiles = Array.from(new Set(files.filter(Boolean))).sort();
112
128
  if (value === '*' && scopedFiles.length === 0 && !allowUnscopedWildcard) {
113
129
  throw new Error('Wildcard value ignores must be scoped with --file <glob>.');
114
130
  }
@@ -226,12 +242,14 @@ function addValue(cwd, args) {
226
242
  if (parsed.reason) existing.reason = parsed.reason;
227
243
  if (parsed.files.length) existing.files = parsed.files;
228
244
  } else {
245
+ // rule, value, files, createdAt, reason — the same order the normalizers emit,
246
+ // so a fresh entry survives the next write untouched.
229
247
  const entry = {
230
248
  rule: parsed.rule,
231
249
  value: parsed.value,
232
- createdAt: new Date().toISOString(),
233
250
  };
234
251
  if (parsed.files.length) entry.files = parsed.files;
252
+ entry.createdAt = new Date().toISOString();
235
253
  if (parsed.reason) entry.reason = parsed.reason;
236
254
  config.ignoreValues.push(entry);
237
255
  }
@@ -299,7 +317,10 @@ function clear(cwd, args) {
299
317
  }
300
318
 
301
319
  function ignoreValueKey(entry) {
302
- const files = Array.isArray(entry.files) && entry.files.length ? entry.files.join('\x1f') : '';
320
+ // Sorted: a file scope is a set. Comparing stored order made an on-disk scope
321
+ // miss the sorted argv form, so a re-add duplicated the entry and a remove
322
+ // silently failed. Every key that hashes `files` must sort — there are four.
323
+ const files = Array.isArray(entry.files) && entry.files.length ? [...entry.files].sort().join('\x1f') : '';
303
324
  return `${String(entry.rule || '').trim().toLowerCase()}\0${normalizeIgnoreValue(entry.value)}\0${files}`;
304
325
  }
305
326
 
@@ -23,7 +23,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
23
23
  const API_BASE = 'https://impeccable.style';
24
24
 
25
25
  // Provider folder names in project roots
26
- const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev'];
26
+ const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.grok', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev', '.vibe'];
27
27
  const PROVIDER_ALIASES = {
28
28
  agents: '.agents',
29
29
  claude: '.claude',
@@ -33,6 +33,9 @@ const PROVIDER_ALIASES = {
33
33
  cursor: '.cursor',
34
34
  gemini: '.gemini',
35
35
  github: '.github',
36
+ grok: '.grok',
37
+ 'grok-build': '.grok',
38
+ xai: '.grok',
36
39
  kiro: '.kiro',
37
40
  opencode: '.opencode',
38
41
  pi: '.pi',
@@ -41,6 +44,7 @@ const PROVIDER_ALIASES = {
41
44
  rovodev: '.rovodev',
42
45
  trae: '.trae',
43
46
  'trae-cn': '.trae-cn',
47
+ vibe: '.vibe',
44
48
  };
45
49
 
46
50
  const PROVIDER_DISPLAY = {
@@ -49,6 +53,7 @@ const PROVIDER_DISPLAY = {
49
53
  '.cursor': { name: 'Cursor', input: 'cursor' },
50
54
  '.gemini': { name: 'Gemini CLI', input: 'gemini' },
51
55
  '.github': { name: 'GitHub Copilot', input: 'github' },
56
+ '.grok': { name: 'Grok Build', input: 'grok' },
52
57
  '.kiro': { name: 'Kiro', input: 'kiro' },
53
58
  '.opencode': { name: 'OpenCode', input: 'opencode' },
54
59
  '.pi': { name: 'Project Indigo', input: 'pi' },
@@ -56,8 +61,9 @@ const PROVIDER_DISPLAY = {
56
61
  '.rovodev': { name: 'Rovo Dev', input: 'rovo-dev' },
57
62
  '.trae': { name: 'Trae', input: 'trae' },
58
63
  '.trae-cn': { name: 'Trae CN', input: 'trae-cn' },
64
+ '.vibe': { name: 'Mistral Vibe', input: 'vibe' },
59
65
  };
60
- const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev'];
66
+ const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe'];
61
67
 
62
68
  // Providers whose GLOBAL (home) skills dir is not `<provider>/skills`.
63
69
  // Pi discovers global skills from ~/.pi/agent/skills/; project scope
@@ -74,11 +80,13 @@ const GLOBAL_HARNESS_HINTS = [
74
80
  { home: '.codex', provider: '.agents' },
75
81
  { home: '.cursor', provider: '.cursor' },
76
82
  { home: '.gemini', provider: '.gemini' },
83
+ { home: '.grok', provider: '.grok' },
77
84
  { home: '.kiro', provider: '.kiro' },
78
85
  { home: '.opencode', provider: '.opencode' },
79
86
  { home: '.pi', provider: '.pi' },
80
87
  { home: '.qoder', provider: '.qoder' },
81
88
  { home: '.rovodev', provider: '.rovodev' },
89
+ { home: '.vibe', provider: '.vibe' },
82
90
  ];
83
91
 
84
92
  // Last-resort default when nothing is detected: Claude Code + the universal
@@ -117,6 +125,12 @@ const PROVIDER_HOOK_ARTIFACTS = {
117
125
  '.github': [
118
126
  { sourceProvider: '.github', rel: 'hooks/impeccable.json', destProvider: '.github' },
119
127
  ],
128
+ // Grok Build discovers project hooks from `.grok/hooks/*.json`. Team-shared
129
+ // by default (commit them if the whole team uses Grok); folder trust is still
130
+ // required via `/hooks-trust` or `--trust` before they run.
131
+ '.grok': [
132
+ { sourceProvider: '.grok', rel: 'hooks/impeccable.json', destProvider: '.grok' },
133
+ ],
120
134
  };
121
135
 
122
136
  function userProviderSkillsDir(home, provider) {
@@ -568,7 +582,7 @@ async function copyOrExtractLocalBundle(sourceValue) {
568
582
  */
569
583
  function normalizeForHash(content) {
570
584
  return content
571
- .replace(/\.(claude|cursor|agents|github|gemini|codex|kiro|opencode|pi|qoder|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/');
585
+ .replace(/\.(claude|cursor|agents|github|gemini|codex|grok|kiro|opencode|pi|qoder|trae|trae-cn|rovodev|vibe)\/skills\//g, '.PROVIDER/skills/');
572
586
  }
573
587
 
574
588
  function hashSkillFile(filePath) {
@@ -1181,21 +1195,52 @@ function hookScriptPathForProvider(skillRoot, provider) {
1181
1195
  return null;
1182
1196
  }
1183
1197
 
1184
- function rewriteHookCommandsForSkillRoot(value, provider, skillRoot) {
1198
+ // Wrap a `node "PATH"` hook command so a missing skill file is a silent no-op
1199
+ // (exit 0) instead of a Node module-resolution crash. hook.mjs promises to
1200
+ // "never break a turn. Always exit 0.", but that only holds once Node can load
1201
+ // the file; a stale/missing path crashes before any of that logic runs. The
1202
+ // `[ ! -f X ] || node X` form (NOT `... || true`) preserves Node's own exit
1203
+ // code when the file exists, so Claude's exit-2 blocking signal still reaches
1204
+ // the agent. POSIX-shell form, consistent with the project's other hook
1205
+ // commands (e.g. the GitHub manifest's `$(git rev-parse ...)`).
1206
+ function guardHookCommand(quotedPath) {
1207
+ return `[ ! -f ${quotedPath} ] || node ${quotedPath}`;
1208
+ }
1209
+
1210
+ // Transform bundled hook commands for the actual install target:
1211
+ // * absolute — rewrite the (marker) command to the resolved absolute skill
1212
+ // path. Required when the manifest is a user/global file (~/.claude/
1213
+ // settings.local.json) that fires in EVERY project, so ${CLAUDE_PROJECT_DIR}
1214
+ // would resolve per-project to dirs without a skill copy (issue #399); also
1215
+ // when a project hook points at a skill installed elsewhere (--scope=global).
1216
+ // * otherwise — keep the bundle's own ${CLAUDE_PROJECT_DIR}-relative path,
1217
+ // which correctly resolves for a project-scoped install.
1218
+ // Either way the command is wrapped with the missing-file guard.
1219
+ function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute }) {
1185
1220
  const hookScript = hookScriptPathForProvider(skillRoot, provider);
1221
+ // Providers we don't own a `node "PATH"` command hook for (.github, .grok)
1222
+ // carry their own portable command forms; leave them untouched.
1186
1223
  if (!hookScript) return value;
1187
1224
 
1188
1225
  if (typeof value === 'string') {
1189
- if (valueHasImpeccableHookMarker(value)) return `node ${JSON.stringify(hookScript)}`;
1190
- return value;
1226
+ if (!valueHasImpeccableHookMarker(value)) return value;
1227
+ let quotedPath;
1228
+ if (absolute) {
1229
+ quotedPath = JSON.stringify(hookScript);
1230
+ } else {
1231
+ // Preserve the bundle's own path token (e.g. ${CLAUDE_PROJECT_DIR}/...).
1232
+ const match = value.match(/"([^"]+)"/);
1233
+ quotedPath = match ? JSON.stringify(match[1]) : JSON.stringify(hookScript);
1234
+ }
1235
+ return guardHookCommand(quotedPath);
1191
1236
  }
1192
1237
  if (Array.isArray(value)) {
1193
- return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, skillRoot));
1238
+ return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, { skillRoot, absolute }));
1194
1239
  }
1195
1240
  if (value && typeof value === 'object') {
1196
1241
  const next = {};
1197
1242
  for (const [key, child] of Object.entries(value)) {
1198
- next[key] = rewriteHookCommandsForSkillRoot(child, provider, skillRoot);
1243
+ next[key] = rewriteHookCommandsForSkillRoot(child, provider, { skillRoot, absolute });
1199
1244
  }
1200
1245
  return next;
1201
1246
  }
@@ -1377,9 +1422,14 @@ function copyProviderHooks(bundleDir, root, providers, { force = false, skillRoo
1377
1422
  }
1378
1423
 
1379
1424
  const freshManifest = readJsonFile(src, 'Bundled hook manifest');
1380
- const fresh = skillRoot === root
1381
- ? freshManifest
1382
- : rewriteHookCommandsForSkillRoot(freshManifest, provider, skillRoot);
1425
+ // Rewrite to an absolute skill path when the skill lives elsewhere than
1426
+ // this manifest's root (--scope=global project hook) OR when the manifest
1427
+ // itself is a user/global file. A global settings file fires in every
1428
+ // project, so ${CLAUDE_PROJECT_DIR} there crashes Node wherever no local
1429
+ // skill copy exists (issue #399); the resolved absolute path is correct
1430
+ // for the one global skill it targets.
1431
+ const absolute = skillRoot !== root || isHomeDir(root);
1432
+ const fresh = rewriteHookCommandsForSkillRoot(freshManifest, provider, { skillRoot, absolute });
1383
1433
  let next = fresh;
1384
1434
 
1385
1435
  if (existsSync(dest)) {
@@ -1727,6 +1777,67 @@ function findInstalledProviders(root, scope) {
1727
1777
  return found;
1728
1778
  }
1729
1779
 
1780
+ // Like findInstalledProviders, but only counts a provider whose skills dir
1781
+ // actually holds the IMPECCABLE skill (canonical, prefixed, or legacy teach-).
1782
+ // `update` uses this so it never mistakes a repo that vendors OTHER first-party
1783
+ // skills under .claude/skills for an impeccable install and drops a copy in
1784
+ // (issue #399, part 2).
1785
+ function findImpeccableProviders(root, scope) {
1786
+ const found = [];
1787
+ for (const d of PROVIDER_DIRS) {
1788
+ for (const skillsDir of existingSkillsDirs(root, d, scope)) {
1789
+ let entries;
1790
+ try { entries = readdirSync(skillsDir); } catch { continue; }
1791
+ if (entries.some(e =>
1792
+ e === 'impeccable' || e.endsWith('-impeccable') ||
1793
+ e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
1794
+ )) {
1795
+ found.push(d);
1796
+ break;
1797
+ }
1798
+ }
1799
+ }
1800
+ return found;
1801
+ }
1802
+
1803
+ // Resolve which install `skills update` should refresh: project-level (the CWD's
1804
+ // git root) or user-level (~/.claude etc.). Returns a plain descriptor; the
1805
+ // caller handles the interactive both-exist prompt via `ambiguous`.
1806
+ function resolveUpdateTarget({ projectRoot, home, explicitScope }) {
1807
+ // A home-rooted repo (a dotfiles checkout at $HOME) overlaps project and user
1808
+ // installs under one root; keep the historical unscoped scan so overlapping
1809
+ // layouts (e.g. Pi's ~/.pi/skills and ~/.pi/agent/skills) both refresh.
1810
+ const homeRooted = isHomeDir(projectRoot);
1811
+ if (homeRooted && !explicitScope) {
1812
+ const providers = findInstalledProviders(home);
1813
+ return providers.length ? { root: home, scope: undefined, providers, scopeLabel: 'user level' } : null;
1814
+ }
1815
+
1816
+ const projectProviders = homeRooted ? [] : findImpeccableProviders(projectRoot, 'project');
1817
+ const userProviders = findImpeccableProviders(home, 'user');
1818
+
1819
+ if (explicitScope === 'user') {
1820
+ return userProviders.length
1821
+ ? { root: home, scope: 'user', providers: userProviders, scopeLabel: 'user level' }
1822
+ : null;
1823
+ }
1824
+ if (explicitScope === 'project') {
1825
+ return projectProviders.length
1826
+ ? { root: projectRoot, scope: 'project', providers: projectProviders, scopeLabel: 'this project' }
1827
+ : null;
1828
+ }
1829
+ if (projectProviders.length && userProviders.length) {
1830
+ return { ambiguous: true, projectRoot, home, projectProviders, userProviders };
1831
+ }
1832
+ if (projectProviders.length) {
1833
+ return { root: projectRoot, scope: 'project', providers: projectProviders, scopeLabel: 'this project' };
1834
+ }
1835
+ if (userProviders.length) {
1836
+ return { root: home, scope: 'user', providers: userProviders, scopeLabel: 'user level' };
1837
+ }
1838
+ return null;
1839
+ }
1840
+
1730
1841
  function findLinkedProviders(root, providers, scope) {
1731
1842
  return providers.filter(provider => {
1732
1843
  for (const skillsDir of providerSkillsDirCandidates(root, provider, scope)) {
@@ -1786,21 +1897,56 @@ async function update(flags = []) {
1786
1897
  const yes = flags.includes('-y') || flags.includes('--yes');
1787
1898
  const force = flags.includes('--force');
1788
1899
  const installHooks = !flags.includes('--no-hooks');
1900
+ const scopeValue = getInstallScopeValue(flags);
1901
+ const explicitScope = normalizeInstallScope(scopeValue);
1902
+ if (scopeValue && !explicitScope) {
1903
+ console.error(`Unknown update scope: ${scopeValue}. Use --project or --user.`);
1904
+ process.exit(1);
1905
+ }
1789
1906
 
1790
1907
  // Download the latest skills directly from impeccable.style.
1791
1908
  // We skip `npx skills update` because it has a known upstream bug
1792
1909
  // (vercel-labs/skills#775) where it can't find the lock file.
1793
- const root = findProjectRoot();
1794
- const providers = findInstalledProviders(root);
1795
- const linkedProviders = findLinkedProviders(root, providers);
1796
- const copyProviders = providers.filter(provider => !linkedProviders.includes(provider));
1910
+ const projectRoot = findProjectRoot();
1911
+ const home = homedir();
1797
1912
 
1798
- if (providers.length === 0) {
1799
- console.log('No impeccable skill folders found in this project.');
1913
+ let target = resolveUpdateTarget({ projectRoot, home, explicitScope });
1914
+ if (!target) {
1915
+ if (explicitScope) {
1916
+ const where = explicitScope === 'user' ? `user level (${formatPathForDisplay(home)})` : `this project (${projectRoot})`;
1917
+ console.log(`No impeccable skill folders found at the ${where}.`);
1918
+ } else {
1919
+ console.log('No impeccable skill folders found in this project or at the user level.');
1920
+ }
1800
1921
  console.log('Run `npx impeccable install` to install first.');
1801
1922
  process.exit(1);
1802
1923
  }
1803
1924
 
1925
+ // Both a project and a user-level install exist and no scope was given. Never
1926
+ // silently pick (issue #399, part 2): prompt when interactive, else default to
1927
+ // the project and say how to target the other.
1928
+ if (target.ambiguous) {
1929
+ console.log('Impeccable is installed both here and at the user level:');
1930
+ console.log(` project ${projectRoot} (${target.projectProviders.join(', ')})`);
1931
+ console.log(` user level ${formatPathForDisplay(home)} (${target.userProviders.join(', ')})`);
1932
+ let pickUser = false;
1933
+ if (!yes && process.stdin.isTTY) {
1934
+ const ans = await ask('Update which? [project]/user: ');
1935
+ pickUser = ['user', 'u', 'global', 'home'].includes(ans);
1936
+ } else {
1937
+ console.log('Defaulting to the project. Re-run with --user to update the user-level install instead.');
1938
+ }
1939
+ target = pickUser
1940
+ ? { root: home, scope: 'user', providers: target.userProviders, scopeLabel: 'user level' }
1941
+ : { root: projectRoot, scope: 'project', providers: target.projectProviders, scopeLabel: 'this project' };
1942
+ }
1943
+
1944
+ const { root, scope } = target;
1945
+ console.log(`Updating the ${target.scopeLabel} install: ${formatPathForDisplay(root)} (${target.providers.join(', ')})`);
1946
+ const providers = target.providers;
1947
+ const linkedProviders = findLinkedProviders(root, providers, scope);
1948
+ const copyProviders = providers.filter(provider => !linkedProviders.includes(provider));
1949
+
1804
1950
  if (linkedProviders.length > 0) {
1805
1951
  console.log(`Linked skills found in: ${linkedProviders.join(', ')}`);
1806
1952
  console.log('Update the source checkout with `git submodule update --remote`, then rerun `npx impeccable link --source=.impeccable` if new skills are added.');
@@ -1819,12 +1965,12 @@ async function update(flags = []) {
1819
1965
  }
1820
1966
 
1821
1967
  // Compare local vs remote -- skip if already up to date
1822
- if (isUpToDate(root, copyProviders, tmpDir)) {
1968
+ if (isUpToDate(root, copyProviders, tmpDir, scope)) {
1823
1969
  try {
1824
1970
  const wantHooks = installHooks && await decideHookInstall(root, copyProviders, { yes });
1825
1971
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, copyProviders, { force }) : [];
1826
1972
  rmSync(tmpDir, { recursive: true, force: true });
1827
- const v = getSkillsVersion(root);
1973
+ const v = getSkillsVersion(root, scope);
1828
1974
  console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
1829
1975
  if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
1830
1976
  console.log('Nothing else to do.');
@@ -1851,16 +1997,16 @@ async function update(flags = []) {
1851
1997
 
1852
1998
  // Retire any old `i-`-prefixed install up front so the refresh lands on the
1853
1999
  // canonical `impeccable` dir rather than orphaning the prefixed copy.
1854
- const migrated = migrateUnprefixImpeccable(root);
2000
+ const migrated = migrateUnprefixImpeccable(root, scope);
1855
2001
  if (migrated > 0) console.log('Migrated a prefixed install back to /impeccable (the i- prefix is no longer used).');
1856
2002
 
1857
- const updated = refreshProviderSkills(tmpDir, root, copyProviders);
2003
+ const updated = refreshProviderSkills(tmpDir, root, copyProviders, scope);
1858
2004
  const wantHooks = installHooks && await decideHookInstall(root, providers, { yes });
1859
2005
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, providers, { force }) : [];
1860
2006
 
1861
2007
  rmSync(tmpDir, { recursive: true, force: true });
1862
2008
 
1863
- const v = getSkillsVersion(root);
2009
+ const v = getSkillsVersion(root, scope);
1864
2010
  console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
1865
2011
  if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
1866
2012
  console.log('Done!\n');