impeccable 3.3.0 → 3.4.0

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 58 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 60 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
- 58 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 60 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 58 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 60 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
- 58 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 60 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 58 deterministic detector rules for AI-generated frontend design.
3
+ Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 60 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
- - **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.
16
+ - **60 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
 
@@ -377,7 +377,7 @@ npx impeccable ignores add-file "src/legacy/**"
377
377
  npx impeccable ignores add-value overused-font Inter --reason "Brand font"
378
378
  ```
379
379
 
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).
380
+ The detector catches 60 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).
381
381
 
382
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.
383
383
 
@@ -9,7 +9,7 @@
9
9
  */
10
10
 
11
11
  import { execSync } from 'node:child_process';
12
- import { existsSync, readFileSync, readdirSync, statSync, lstatSync, unlinkSync, mkdirSync, writeFileSync, rmSync, renameSync, createWriteStream, realpathSync, symlinkSync, readlinkSync, cpSync } from 'node:fs';
12
+ import { existsSync, readFileSync, readdirSync, statSync, lstatSync, unlinkSync, mkdirSync, writeFileSync, rmSync, rmdirSync, renameSync, createWriteStream, realpathSync, symlinkSync, readlinkSync, cpSync } from 'node:fs';
13
13
  import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
14
14
  import { createInterface, emitKeypressEvents } from 'node:readline';
15
15
  import { fileURLToPath } from 'node:url';
@@ -65,11 +65,23 @@ const PROVIDER_DISPLAY = {
65
65
  };
66
66
  const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe'];
67
67
 
68
- // Providers whose GLOBAL (home) skills dir is not `<provider>/skills`.
69
- // Pi discovers global skills from ~/.pi/agent/skills/; project scope
70
- // stays .pi/skills/. See issue #327.
68
+ // OpenCode reads global skills from its config directory, not ~/.opencode:
69
+ // $OPENCODE_CONFIG_DIR, else $XDG_CONFIG_HOME/opencode, else
70
+ // ~/.config/opencode. Writing to ~/.opencode/skills produced an install
71
+ // `opencode debug skill` never listed. See issue #406.
72
+ function opencodeGlobalConfigDir(home) {
73
+ if (process.env.OPENCODE_CONFIG_DIR) return process.env.OPENCODE_CONFIG_DIR;
74
+ if (process.env.XDG_CONFIG_HOME) return join(process.env.XDG_CONFIG_HOME, 'opencode');
75
+ return join(home, '.config', 'opencode');
76
+ }
77
+
78
+ // Providers whose GLOBAL (home) skills dir is not `<provider>/skills`,
79
+ // as a function of the home dir. Pi discovers global skills from
80
+ // ~/.pi/agent/skills/ (issue #327); OpenCode from its config dir (issue
81
+ // #406). Project scope stays `<provider>/skills` for both.
71
82
  const HOME_SKILLS_DIR_OVERRIDES = {
72
- '.pi': join('.pi', 'agent', 'skills'),
83
+ '.pi': (home) => join(home, '.pi', 'agent', 'skills'),
84
+ '.opencode': (home) => join(opencodeGlobalConfigDir(home), 'skills'),
73
85
  };
74
86
 
75
87
  // When a project has no harness folder yet, infer the target from globally
@@ -83,6 +95,9 @@ const GLOBAL_HARNESS_HINTS = [
83
95
  { home: '.grok', provider: '.grok' },
84
96
  { home: '.kiro', provider: '.kiro' },
85
97
  { home: '.opencode', provider: '.opencode' },
98
+ // OpenCode's real global config dir (issue #406); the ~/.opencode entry
99
+ // above keeps recognizing machines that only have the legacy dir.
100
+ { resolve: opencodeGlobalConfigDir, provider: '.opencode' },
86
101
  { home: '.pi', provider: '.pi' },
87
102
  { home: '.qoder', provider: '.qoder' },
88
103
  { home: '.rovodev', provider: '.rovodev' },
@@ -134,7 +149,8 @@ const PROVIDER_HOOK_ARTIFACTS = {
134
149
  };
135
150
 
136
151
  function userProviderSkillsDir(home, provider) {
137
- if (HOME_SKILLS_DIR_OVERRIDES[provider]) return join(home, HOME_SKILLS_DIR_OVERRIDES[provider]);
152
+ const override = HOME_SKILLS_DIR_OVERRIDES[provider];
153
+ if (override) return override(home);
138
154
  return join(home, provider, 'skills');
139
155
  }
140
156
 
@@ -861,10 +877,15 @@ function collectInstallDetections(root, home = homedir()) {
861
877
  });
862
878
  }
863
879
 
864
- for (const { home: h, provider } of GLOBAL_HARNESS_HINTS) {
865
- const foundPath = join(home, h);
880
+ for (const hint of GLOBAL_HARNESS_HINTS) {
881
+ const { provider } = hint;
882
+ // A hint is either a fixed dir under home or a resolver for harnesses
883
+ // whose location depends on the environment (OpenCode's config dir).
884
+ const foundPath = hint.resolve ? hint.resolve(home) : join(home, hint.home);
866
885
  if (!existsSync(foundPath)) continue;
867
- const skillProbePaths = userSkillProbePaths(home, h, provider);
886
+ const skillProbePaths = hint.resolve
887
+ ? uniquePaths([userProviderSkillsDir(home, provider), join(foundPath, 'skills')])
888
+ : userSkillProbePaths(home, hint.home, provider);
868
889
  detections.push({
869
890
  provider,
870
891
  scope: 'user',
@@ -1137,6 +1158,32 @@ function copyProviderSkills(bundleDir, root, targets, { scope } = {}) {
1137
1158
  copyDirSync(src, dest);
1138
1159
  written++;
1139
1160
  }
1161
+ // A pre-#406 global OpenCode install lived at ~/.opencode/skills, a
1162
+ // location OpenCode never reads. Now that the real copy sits in the
1163
+ // config dir, drop exactly the skills just written from the stranded
1164
+ // location; sibling skills and everything else in ~/.opencode stay.
1165
+ // Guards (both flagged in review): a symlinked skills dir is shared
1166
+ // storage whose target must not be emptied through the link, the
1167
+ // just-written dir must be compared by realpath rather than string,
1168
+ // and a home-rooted repo makes `.opencode/skills` a live
1169
+ // project-scope install rather than a stranded global one.
1170
+ if (scope === 'user' && provider === '.opencode') {
1171
+ const legacyDir = join(root, '.opencode', 'skills');
1172
+ let migratable = false;
1173
+ try {
1174
+ migratable = existsSync(legacyDir)
1175
+ && !lstatSync(legacyDir).isSymbolicLink()
1176
+ && realpathSync(legacyDir) !== realpathSync(localSkillsDir)
1177
+ && !existsSync(join(root, '.git'));
1178
+ } catch { migratable = false; }
1179
+ if (migratable) {
1180
+ for (const skill of readdirSync(srcDir, { withFileTypes: true })) {
1181
+ if (!skill.isDirectory()) continue;
1182
+ rmSync(join(legacyDir, skill.name), { recursive: true, force: true });
1183
+ }
1184
+ try { rmdirSync(legacyDir); } catch { /* not empty: siblings stay */ }
1185
+ }
1186
+ }
1140
1187
  }
1141
1188
  }
1142
1189
  return written;
@@ -1179,6 +1226,19 @@ function hookArtifactsForProvider(bundleDir, root, provider) {
1179
1226
  });
1180
1227
  }
1181
1228
 
1229
+ // The project-relative hook command path for a provider, used for project-scope
1230
+ // installs (skillRoot === root). Derived rather than copied from the bundle: the
1231
+ // Codex bundle ships a `.codex/skills/...` command (correct for a `.codex`-
1232
+ // directory install), but the CLI lays Codex's skill down at `.agents/skills/`,
1233
+ // so preserving the bundle token would point the hook at a nonexistent file and
1234
+ // silently no-op it. Claude keeps its ${CLAUDE_PROJECT_DIR} token so a manifest
1235
+ // read from a nested cwd (or copied into settings.local.json) still resolves.
1236
+ function hookScriptRelPathForProvider(provider) {
1237
+ const script = provider === '.cursor' ? 'hook-before-edit.mjs' : 'hook.mjs';
1238
+ const rel = `${provider}/skills/impeccable/scripts/${script}`;
1239
+ return provider === '.claude' ? '${CLAUDE_PROJECT_DIR}/' + rel : rel;
1240
+ }
1241
+
1182
1242
  function hookScriptPathForProvider(skillRoot, provider) {
1183
1243
  // `.github` is intentionally absent: its hook manifest (`.github/hooks/
1184
1244
  // impeccable.json`) is a committed, team-shared file that the Copilot cloud
@@ -1195,21 +1255,53 @@ function hookScriptPathForProvider(skillRoot, provider) {
1195
1255
  return null;
1196
1256
  }
1197
1257
 
1198
- function rewriteHookCommandsForSkillRoot(value, provider, skillRoot) {
1258
+ // Wrap a `node "PATH"` hook command so a missing skill file is a silent no-op
1259
+ // (exit 0) instead of a Node module-resolution crash. hook.mjs promises to
1260
+ // "never break a turn. Always exit 0.", but that only holds once Node can load
1261
+ // the file; a stale/missing path crashes before any of that logic runs. The
1262
+ // `[ ! -f X ] || node X` form (NOT `... || true`) preserves Node's own exit
1263
+ // code when the file exists, so Claude's exit-2 blocking signal still reaches
1264
+ // the agent. POSIX-shell form, consistent with the project's other hook
1265
+ // commands (e.g. the GitHub manifest's `$(git rev-parse ...)`).
1266
+ function guardHookCommand(quotedPath) {
1267
+ return `[ ! -f ${quotedPath} ] || node ${quotedPath}`;
1268
+ }
1269
+
1270
+ // Transform bundled hook commands for the actual install target:
1271
+ // * absolute — rewrite the (marker) command to the resolved absolute skill
1272
+ // path. Required when the manifest is a user/global file (~/.claude/
1273
+ // settings.local.json) that fires in EVERY project, so ${CLAUDE_PROJECT_DIR}
1274
+ // would resolve per-project to dirs without a skill copy (issue #399); also
1275
+ // when a project hook points at a skill installed elsewhere (--scope=global).
1276
+ // * otherwise — keep the bundle's own ${CLAUDE_PROJECT_DIR}-relative path,
1277
+ // which correctly resolves for a project-scoped install.
1278
+ // Either way the command is wrapped with the missing-file guard.
1279
+ function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute }) {
1199
1280
  const hookScript = hookScriptPathForProvider(skillRoot, provider);
1281
+ // Providers we don't own a `node "PATH"` command hook for (.github, .grok)
1282
+ // carry their own portable command forms; leave them untouched.
1200
1283
  if (!hookScript) return value;
1201
1284
 
1202
1285
  if (typeof value === 'string') {
1203
- if (valueHasImpeccableHookMarker(value)) return `node ${JSON.stringify(hookScript)}`;
1204
- return value;
1286
+ if (!valueHasImpeccableHookMarker(value)) return value;
1287
+ let quotedPath;
1288
+ if (absolute) {
1289
+ quotedPath = JSON.stringify(hookScript);
1290
+ } else {
1291
+ // Project-scope install: derive the provider's own project-relative path
1292
+ // rather than trusting the bundle token, which for Codex points at
1293
+ // `.codex/skills/...` while the CLI installs the skill at `.agents/skills/`.
1294
+ quotedPath = JSON.stringify(hookScriptRelPathForProvider(provider));
1295
+ }
1296
+ return guardHookCommand(quotedPath);
1205
1297
  }
1206
1298
  if (Array.isArray(value)) {
1207
- return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, skillRoot));
1299
+ return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, { skillRoot, absolute }));
1208
1300
  }
1209
1301
  if (value && typeof value === 'object') {
1210
1302
  const next = {};
1211
1303
  for (const [key, child] of Object.entries(value)) {
1212
- next[key] = rewriteHookCommandsForSkillRoot(child, provider, skillRoot);
1304
+ next[key] = rewriteHookCommandsForSkillRoot(child, provider, { skillRoot, absolute });
1213
1305
  }
1214
1306
  return next;
1215
1307
  }
@@ -1391,9 +1483,14 @@ function copyProviderHooks(bundleDir, root, providers, { force = false, skillRoo
1391
1483
  }
1392
1484
 
1393
1485
  const freshManifest = readJsonFile(src, 'Bundled hook manifest');
1394
- const fresh = skillRoot === root
1395
- ? freshManifest
1396
- : rewriteHookCommandsForSkillRoot(freshManifest, provider, skillRoot);
1486
+ // Rewrite to an absolute skill path when the skill lives elsewhere than
1487
+ // this manifest's root (--scope=global project hook) OR when the manifest
1488
+ // itself is a user/global file. A global settings file fires in every
1489
+ // project, so ${CLAUDE_PROJECT_DIR} there crashes Node wherever no local
1490
+ // skill copy exists (issue #399); the resolved absolute path is correct
1491
+ // for the one global skill it targets.
1492
+ const absolute = skillRoot !== root || isHomeDir(root);
1493
+ const fresh = rewriteHookCommandsForSkillRoot(freshManifest, provider, { skillRoot, absolute });
1397
1494
  let next = fresh;
1398
1495
 
1399
1496
  if (existsSync(dest)) {
@@ -1741,6 +1838,67 @@ function findInstalledProviders(root, scope) {
1741
1838
  return found;
1742
1839
  }
1743
1840
 
1841
+ // Like findInstalledProviders, but only counts a provider whose skills dir
1842
+ // actually holds the IMPECCABLE skill (canonical, prefixed, or legacy teach-).
1843
+ // `update` uses this so it never mistakes a repo that vendors OTHER first-party
1844
+ // skills under .claude/skills for an impeccable install and drops a copy in
1845
+ // (issue #399, part 2).
1846
+ function findImpeccableProviders(root, scope) {
1847
+ const found = [];
1848
+ for (const d of PROVIDER_DIRS) {
1849
+ for (const skillsDir of existingSkillsDirs(root, d, scope)) {
1850
+ let entries;
1851
+ try { entries = readdirSync(skillsDir); } catch { continue; }
1852
+ if (entries.some(e =>
1853
+ e === 'impeccable' || e.endsWith('-impeccable') ||
1854
+ e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
1855
+ )) {
1856
+ found.push(d);
1857
+ break;
1858
+ }
1859
+ }
1860
+ }
1861
+ return found;
1862
+ }
1863
+
1864
+ // Resolve which install `skills update` should refresh: project-level (the CWD's
1865
+ // git root) or user-level (~/.claude etc.). Returns a plain descriptor; the
1866
+ // caller handles the interactive both-exist prompt via `ambiguous`.
1867
+ function resolveUpdateTarget({ projectRoot, home, explicitScope }) {
1868
+ // A home-rooted repo (a dotfiles checkout at $HOME) overlaps project and user
1869
+ // installs under one root; keep the historical unscoped scan so overlapping
1870
+ // layouts (e.g. Pi's ~/.pi/skills and ~/.pi/agent/skills) both refresh.
1871
+ const homeRooted = isHomeDir(projectRoot);
1872
+ if (homeRooted && !explicitScope) {
1873
+ const providers = findInstalledProviders(home);
1874
+ return providers.length ? { root: home, scope: undefined, providers, scopeLabel: 'user level' } : null;
1875
+ }
1876
+
1877
+ const projectProviders = homeRooted ? [] : findImpeccableProviders(projectRoot, 'project');
1878
+ const userProviders = findImpeccableProviders(home, 'user');
1879
+
1880
+ if (explicitScope === 'user') {
1881
+ return userProviders.length
1882
+ ? { root: home, scope: 'user', providers: userProviders, scopeLabel: 'user level' }
1883
+ : null;
1884
+ }
1885
+ if (explicitScope === 'project') {
1886
+ return projectProviders.length
1887
+ ? { root: projectRoot, scope: 'project', providers: projectProviders, scopeLabel: 'this project' }
1888
+ : null;
1889
+ }
1890
+ if (projectProviders.length && userProviders.length) {
1891
+ return { ambiguous: true, projectRoot, home, projectProviders, userProviders };
1892
+ }
1893
+ if (projectProviders.length) {
1894
+ return { root: projectRoot, scope: 'project', providers: projectProviders, scopeLabel: 'this project' };
1895
+ }
1896
+ if (userProviders.length) {
1897
+ return { root: home, scope: 'user', providers: userProviders, scopeLabel: 'user level' };
1898
+ }
1899
+ return null;
1900
+ }
1901
+
1744
1902
  function findLinkedProviders(root, providers, scope) {
1745
1903
  return providers.filter(provider => {
1746
1904
  for (const skillsDir of providerSkillsDirCandidates(root, provider, scope)) {
@@ -1800,21 +1958,56 @@ async function update(flags = []) {
1800
1958
  const yes = flags.includes('-y') || flags.includes('--yes');
1801
1959
  const force = flags.includes('--force');
1802
1960
  const installHooks = !flags.includes('--no-hooks');
1961
+ const scopeValue = getInstallScopeValue(flags);
1962
+ const explicitScope = normalizeInstallScope(scopeValue);
1963
+ if (scopeValue && !explicitScope) {
1964
+ console.error(`Unknown update scope: ${scopeValue}. Use --project or --user.`);
1965
+ process.exit(1);
1966
+ }
1803
1967
 
1804
1968
  // Download the latest skills directly from impeccable.style.
1805
1969
  // We skip `npx skills update` because it has a known upstream bug
1806
1970
  // (vercel-labs/skills#775) where it can't find the lock file.
1807
- const root = findProjectRoot();
1808
- const providers = findInstalledProviders(root);
1809
- const linkedProviders = findLinkedProviders(root, providers);
1810
- const copyProviders = providers.filter(provider => !linkedProviders.includes(provider));
1971
+ const projectRoot = findProjectRoot();
1972
+ const home = homedir();
1811
1973
 
1812
- if (providers.length === 0) {
1813
- console.log('No impeccable skill folders found in this project.');
1974
+ let target = resolveUpdateTarget({ projectRoot, home, explicitScope });
1975
+ if (!target) {
1976
+ if (explicitScope) {
1977
+ const where = explicitScope === 'user' ? `user level (${formatPathForDisplay(home)})` : `this project (${projectRoot})`;
1978
+ console.log(`No impeccable skill folders found at the ${where}.`);
1979
+ } else {
1980
+ console.log('No impeccable skill folders found in this project or at the user level.');
1981
+ }
1814
1982
  console.log('Run `npx impeccable install` to install first.');
1815
1983
  process.exit(1);
1816
1984
  }
1817
1985
 
1986
+ // Both a project and a user-level install exist and no scope was given. Never
1987
+ // silently pick (issue #399, part 2): prompt when interactive, else default to
1988
+ // the project and say how to target the other.
1989
+ if (target.ambiguous) {
1990
+ console.log('Impeccable is installed both here and at the user level:');
1991
+ console.log(` project ${projectRoot} (${target.projectProviders.join(', ')})`);
1992
+ console.log(` user level ${formatPathForDisplay(home)} (${target.userProviders.join(', ')})`);
1993
+ let pickUser = false;
1994
+ if (!yes && process.stdin.isTTY) {
1995
+ const ans = await ask('Update which? [project]/user: ');
1996
+ pickUser = ['user', 'u', 'global', 'home'].includes(ans);
1997
+ } else {
1998
+ console.log('Defaulting to the project. Re-run with --user to update the user-level install instead.');
1999
+ }
2000
+ target = pickUser
2001
+ ? { root: home, scope: 'user', providers: target.userProviders, scopeLabel: 'user level' }
2002
+ : { root: projectRoot, scope: 'project', providers: target.projectProviders, scopeLabel: 'this project' };
2003
+ }
2004
+
2005
+ const { root, scope } = target;
2006
+ console.log(`Updating the ${target.scopeLabel} install: ${formatPathForDisplay(root)} (${target.providers.join(', ')})`);
2007
+ const providers = target.providers;
2008
+ const linkedProviders = findLinkedProviders(root, providers, scope);
2009
+ const copyProviders = providers.filter(provider => !linkedProviders.includes(provider));
2010
+
1818
2011
  if (linkedProviders.length > 0) {
1819
2012
  console.log(`Linked skills found in: ${linkedProviders.join(', ')}`);
1820
2013
  console.log('Update the source checkout with `git submodule update --remote`, then rerun `npx impeccable link --source=.impeccable` if new skills are added.');
@@ -1833,12 +2026,12 @@ async function update(flags = []) {
1833
2026
  }
1834
2027
 
1835
2028
  // Compare local vs remote -- skip if already up to date
1836
- if (isUpToDate(root, copyProviders, tmpDir)) {
2029
+ if (isUpToDate(root, copyProviders, tmpDir, scope)) {
1837
2030
  try {
1838
2031
  const wantHooks = installHooks && await decideHookInstall(root, copyProviders, { yes });
1839
2032
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, copyProviders, { force }) : [];
1840
2033
  rmSync(tmpDir, { recursive: true, force: true });
1841
- const v = getSkillsVersion(root);
2034
+ const v = getSkillsVersion(root, scope);
1842
2035
  console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
1843
2036
  if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
1844
2037
  console.log('Nothing else to do.');
@@ -1865,16 +2058,16 @@ async function update(flags = []) {
1865
2058
 
1866
2059
  // Retire any old `i-`-prefixed install up front so the refresh lands on the
1867
2060
  // canonical `impeccable` dir rather than orphaning the prefixed copy.
1868
- const migrated = migrateUnprefixImpeccable(root);
2061
+ const migrated = migrateUnprefixImpeccable(root, scope);
1869
2062
  if (migrated > 0) console.log('Migrated a prefixed install back to /impeccable (the i- prefix is no longer used).');
1870
2063
 
1871
- const updated = refreshProviderSkills(tmpDir, root, copyProviders);
2064
+ const updated = refreshProviderSkills(tmpDir, root, copyProviders, scope);
1872
2065
  const wantHooks = installHooks && await decideHookInstall(root, providers, { yes });
1873
2066
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, providers, { force }) : [];
1874
2067
 
1875
2068
  rmSync(tmpDir, { recursive: true, force: true });
1876
2069
 
1877
- const v = getSkillsVersion(root);
2070
+ const v = getSkillsVersion(root, scope);
1878
2071
  console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
1879
2072
  if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
1880
2073
  console.log('Done!\n');
@@ -530,7 +530,11 @@ if (IS_BROWSER) {
530
530
  function generateSelector(el) {
531
531
  if (el === document.body) return 'body';
532
532
  if (el === document.documentElement) return 'html';
533
- if (el.id) return '#' + CSS.escape(el.id);
533
+ // Read via getAttribute when `el.id` is not a string — a <form> with a
534
+ // named control (e.g. <input name="id">) shadows the builtin getter and
535
+ // returns the element, producing a garbage `#[object …]` selector (#407).
536
+ const elId = typeof el.id === 'string' ? el.id : (el.getAttribute('id') || '');
537
+ if (elId) return '#' + CSS.escape(elId);
534
538
 
535
539
  const parts = [];
536
540
  let current = el;
@@ -1223,6 +1227,10 @@ if (IS_BROWSER) {
1223
1227
  type: f.type || f.id,
1224
1228
  category: ap ? ap.category : 'quality',
1225
1229
  severity: f.severity || ap?.severity || 'warning',
1230
+ // Advisory findings (em-dash overuse, etc.) are surfaced but never
1231
+ // treated as failures; carry the flag so the overlay/extension can
1232
+ // render them with the mildest affordance and consumers can filter.
1233
+ advisory: (ap && ap.advisory === true) || f.advisory === true,
1226
1234
  detail: f.detail || f.snippet,
1227
1235
  ignoreValue: f.ignoreValue || f.value || '',
1228
1236
  name: ap ? ap.name : (f.type || f.id),
@@ -1463,8 +1471,11 @@ if (IS_BROWSER) {
1463
1471
  for (const el of document.querySelectorAll('*')) {
1464
1472
  // Skip impeccable's own elements and any descendants (overlays, labels, banner, nav buttons)
1465
1473
  if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
1466
- // Skip browser extension elements (Claude, etc.)
1467
- const elId = el.id || '';
1474
+ // Skip browser extension elements (Claude, etc.). Use getAttribute when
1475
+ // `el.id` is not a string: a <form> with a named control like
1476
+ // <input name="id"> shadows the builtin `id` getter and returns the
1477
+ // element, whose `.startsWith` throws (issue #407).
1478
+ const elId = typeof el.id === 'string' ? el.id : (el.getAttribute('id') || '');
1468
1479
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
1469
1480
  // Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
1470
1481
  // These are inspector chrome, not part of the user's design.
@@ -1479,6 +1490,7 @@ if (IS_BROWSER) {
1479
1490
  ...checkElementMotionDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1480
1491
  ...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1481
1492
  ...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1493
+ ...checkElementRadialSpotlightDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1482
1494
  ...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1483
1495
  ...checkElementItalicSerifDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1484
1496
  ...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
@@ -1517,7 +1529,7 @@ if (IS_BROWSER) {
1517
1529
  addBrowserFindings(groupMap, document.body, typoFindings);
1518
1530
  }
1519
1531
 
1520
- const sectionKickerFindings = checkRepeatedSectionKickersDOM()
1532
+ const sectionKickerFindings = checkKickerAboveHeadingDOM()
1521
1533
  .map(f => ({ type: f.id, detail: f.snippet }))
1522
1534
  .filter(f => _ruleOk(f.type));
1523
1535
  if (sectionKickerFindings.length > 0) {
@@ -1541,6 +1553,17 @@ if (IS_BROWSER) {
1541
1553
  addBrowserFindings(groupMap, document.body, repeatedTextFindings);
1542
1554
  }
1543
1555
 
1556
+ // Em-dash overuse (advisory): browser parity with the static/regex path.
1557
+ // Reads rendered body text so it catches dashes written as HTML entities.
1558
+ // serializeFindings stamps the advisory flag from the registry.
1559
+ const emDashFindings = checkEmDashOveruseDOM()
1560
+ .map(f => ({ type: f.id, detail: f.snippet }))
1561
+ .filter(f => _ruleOk(f.type));
1562
+ if (emDashFindings.length > 0) {
1563
+ pageLevelFindings.push(...emDashFindings);
1564
+ addBrowserFindings(groupMap, document.body, emDashFindings);
1565
+ }
1566
+
1544
1567
  const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
1545
1568
  for (const f of layoutFindings) {
1546
1569
  const el = f.el || document.body;