docs: impeccable skill maintenance/install reference + CLAUDE.md pointer row

Claude-Session: https://claude.ai/code/session_01DTLFEx7r7AKsLerGtsnu8g

claude/impeccable.md

@@ -0,0 +1,96 @@
+# Impeccable — design skill: install, maintenance, usage
+
+[Impeccable](https://impeccable.style/) (GitHub: `pbakaus/impeccable`, Apache 2.0) is a
+design vocabulary system for AI agents: 23 design commands, a per-project DESIGN.md
+contract, and a deterministic 46-rule anti-slop detector.
+
+## How it is installed here (non-standard — do not "fix")
+
+Two skills in the **user profile** (`~/.claude/skills/`) **and mirrored into every
+`~/.claude-*` profile's `skills/` dir** (octopus, octopus-anthropic, oreillyit,
+oreillyit-anthropic, oreillyit-minimax — not `-secrets`), deliberately arranged so
+the full skill never auto-fires:
+
+| Path | What | Key frontmatter |
+|---|---|---|
+| `~/.claude/skills/impeccable/` | Full skill (SKILL.md + `reference/` + `scripts/`), copied from repo `.claude/skills/impeccable` | `disable-model-invocation: true` **(added locally — not upstream)** |
+| `~/.claude/skills/impeccable-hint/` | Hand-written ~40-line shim carrying Impeccable's original auto-trigger description | `user-invocable: false` |
+
+Rationale: the upstream description is engineered to auto-trigger on almost any
+frontend vocabulary, and a full invocation loads ~10–20k tokens (SKILL.md body +
+mandatory reference reads). The shim auto-fires instead and merely *suggests*
+`/impeccable <command>` to the user (once per session); only the user invokes the
+real skill. Idle cost ≈ one description in the skill listing; hint invocation ≈ a few
+hundred tokens.
+
+Deliberately **not** installed globally:
+- the detector **hook** (`settings.json` → `hook.mjs`) — false-positive-prone on Hugo
+  Go-template source (flags `src="{{ … }}"` as broken-image, em-dashes in comments)
+- the `impeccable-manual-edit-applier` **agent** — only Live mode uses it, and Live
+  mode overlaps hugo-accelerator's editorial widget + branch previews
+
+## Updating to a new upstream version
+
+`npx impeccable install` / the plugin marketplace will NOT maintain this arrangement.
+Update manually:
+
+```bash
+cd "$(mktemp -d)"
+curl -sL https://github.com/pbakaus/impeccable/archive/refs/heads/main.tar.gz | tar xz
+rm -rf ~/.claude/skills/impeccable
+cp -r impeccable-main/.claude/skills/impeccable ~/.claude/skills/
+```
+
+After re-applying the frontmatter edit below, mirror both skill dirs into every
+profile:
+
+```bash
+for p in ~/.claude-octopus ~/.claude-octopus-anthropic ~/.claude-oreillyit \
+         ~/.claude-oreillyit-anthropic ~/.claude-oreillyit-minimax; do
+  rm -rf "$p/skills/impeccable" "$p/skills/impeccable-hint"
+  cp -r ~/.claude/skills/impeccable ~/.claude/skills/impeccable-hint "$p/skills/"
+done
+```
+
+Then **re-apply the local edit** — add below `user-invocable: true` in
+`~/.claude/skills/impeccable/SKILL.md`:
+
+```yaml
+disable-model-invocation: true
+```
+
+If upstream's `description:` changed, copy the new text into
+`~/.claude/skills/impeccable-hint/SKILL.md` so the shim's trigger surface stays in
+sync. If upstream added/renamed commands, refresh the shim's command table.
+
+Installed version: check `version:` in `~/.claude/skills/impeccable/SKILL.md`
+(3.9.1 as of 2026-07-22).
+
+## Detector (no skill involvement, plain npx)
+
+```bash
+npx impeccable detect <path|url> [--json]        # 46 deterministic rules, no LLM
+npx impeccable ignores add-value overused-font Inter --reason "Brand font"
+```
+
+- **Output streams:** the human-readable report goes to **stderr**; `--json` goes to
+  stdout. In CI, capture with `2>&1 | grep -v 'npm WARN'` — a bare `2>/dev/null`
+  silently discards the entire text report.
+
+- Run against **rendered output** (`public/` after a Hugo build), never template
+  source — raw Go templates false-positive.
+- Staging URLs are Authelia-gated → the detector would score the login page; use a
+  local build or port-forward.
+- Needs Node ≥ 22.12 per engines; observed working on Node 18 with EBADENGINE
+  warnings only. Pin the version in any CI use (no `@latest`).
+- Ignores/config live in `.impeccable/config.json` per repo — a template-sync surface
+  if adopted fleet-wide (hugo-accelerator `template_consumers.json`).
+
+## Planned integrations (recommendations, 2026-07-22)
+
+- **hugo-ci (M13):** `npx impeccable detect public/ --json` post-render, advisory
+  first, gate later.
+- **cms-proxy AI edit / M6 drafting:** per-customer DESIGN.md (bootstrap interview or
+  `/impeccable document`) injected into the AI edit prompt alongside component schemas.
+- **agent-runtimes:** detector as post-task verify step for frontend tasks; full skill
+  baked only into design-scoped harness templates (Node 22+ images).