pbakaus_impeccable/site/content/reference/config.md

title, tagline, description, section, order

title	tagline	description	section	order
Config and ignores	Project settings for detector exceptions, hook behavior, and local overrides.	Use .impeccable config for confirmed detector exceptions and runtime settings. Keep product and design intent in PRODUCT.md and DESIGN.md.	concepts	2

Impeccable stores runtime settings under .impeccable/. Most users do not need to hand-edit those files. Use the CLI when you want to record a confirmed exception.

Use config for:

• detector ignores shared by npx impeccable detect and the design hook;
• private local ignores that should not be committed;
• hook lifecycle settings such as enabled, quiet mode, and audit logging.

Use PRODUCT.md and DESIGN.md for product and design intent. See Design Context.

The usual path

List the current ignores:

npx impeccable ignores list

Add the narrowest exception that matches the real reason:

npx impeccable ignores add-value design-system-color "#ff00aa" --reason "Campaign accent"
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-rule side-tab

Remove an exception when the underlying code is fixed:

npx impeccable ignores remove-value design-system-color "#ff00aa"

The same detector config is used by the CLI and the hook, so an ignore behaves consistently in both places.

Shared or local

Default ignores go into .impeccable/config.json. Commit them when they represent team intent: a legacy folder, a confirmed brand exception, or a project-wide rule decision.

Use --local for private work:

npx impeccable ignores add-file "src/private-experiment/**" --local

Local settings go into .impeccable/config.local.json, which Impeccable keeps out of git.

Value ignores

Prefer value ignores when a rule reports a specific value:

npx impeccable ignores add-value overused-font Inter --reason "Brand font"

Fonts, colors, radii, and motion values should usually be suppressed by value, not by whole rule. That keeps the rule useful everywhere else.

Wildcard value ignores are allowed only when scoped to a file:

npx impeccable ignores add-value design-system-color "*" --file "src/demo.css"

That keeps one intentionally experimental file from teaching the whole project that every undocumented color is acceptable.

Details when the default path is not enough

What the config file looks like

The shared config lives at .impeccable/config.json. A typical file looks like this:

{
  "detector": {
    "ignoreRules": [],
    "ignoreFiles": [],
    "ignoreValues": [],
    "designSystem": {
      "enabled": true
    }
  },
  "hook": {
    "enabled": true,
    "quiet": false,
    "auditLog": ".impeccable/hook.ndjson"
  }
}

The detector section is shared by manual scans and hooks. The hook section only controls automatic hook execution and hook output.

Disable design-system checks

Design-aware rules run when DESIGN.md exists. Disable them for the project only when the design file is intentionally not authoritative yet:

{
  "detector": {
    "designSystem": {
      "enabled": false
    }
  }
}

For one manual run, keep config but skip the design-system rules:

npx impeccable detect --no-design-system src/

Use --no-config only when you want a raw scan with no project ignores and no DESIGN.md context.

Hook runtime settings

Use /impeccable hooks for normal lifecycle changes:

/impeccable hooks status
/impeccable hooks on
/impeccable hooks off

hook.quiet: true suppresses clean and pending acknowledgements while still surfacing new findings.

hook.auditLog writes one NDJSON line per hook invocation for debugging. Leave it off during normal work.

Environment variables still override config for one shell: IMPECCABLE_HOOK_DISABLED, IMPECCABLE_HOOK_QUIET, and IMPECCABLE_HOOK_LOG.