ci(skill-check): scan the docs a contributor reads

The check asserts that every make target named in a doc exists, and its
scanned set was .pi/ plus CLAUDE.md.  Since #50, CONTRIBUTING.md is the
document a *human* goes to for a build command, and it names 21 targets
that nothing verified; README.md names none today and is in for the same
reason.  The script's own header sentence is the argument — a renamed
target sends a person off the same cliff it sends an agent off.

The file list is now one `docs` variable used twice, because the failure
message carried a second copy of it and a second list is a second thing
to forget.  The `[ -d .pi ]` guard went with it: gating the whole run on
.pi/ would make the human-facing half conditional on the agent-facing
one, and an empty list is the same "nothing to scan" exit without the
coupling.

The lefthook glob is that scanned set now rather than
{Makefile,.pi/**/*.md} — #220's smaller half, and it did not fire on
CLAUDE.md either, which the script had read for months.

Verified by planting a bad target rather than by reading the diff: both
matched forms in each of the four scanned surfaces, each naming the
right file; the same two plants pass on the pre-change script; unfenced
prose still does not match; and the hook fires on a staged
CONTRIBUTING.md under the new glob where the old one skipped it.  The
count is unchanged at 47 — the set is a union — so coverage is the only
thing that moved.

Closes #220

CLAUDE.md

@@ -161,7 +161,7 @@ make ui-test          # Vitest component/store suite in a real browser (no app)
 make ui-visual        # Same, including toMatchScreenshot comparisons
 make ui-setup         # Install the Vitest provider's own Chromium (once)
 make bindings-check   # Fail if frontend/bindings is stale vs the Go bindings
-make skill-check      # Fail if .pi/ documents a make target that doesn't exist
+make skill-check      # Fail if a doc names a make target that doesn't exist
 make commit-check     # Fail if a commit subject is not a Conventional Commit
 make lint             # golangci-lint v2 (strict), all three build configurations
 make test             # All tests with race detector, all three build configurations

Makefile

@@ -192,7 +192,7 @@ css-check: ## Fail on a css`` literal ended early by a backtick, or a nested rul
 # Every command in them is a make target on purpose, so this is
 # checkable.  It also asserts AGENTS.md is a symlink to CLAUDE.md, so the
 # two harnesses cannot drift onto two descriptions of one project.
-skill-check: ## Fail if the agent docs name a missing make target, or AGENTS.md is not a symlink
+skill-check: ## Fail if the docs name a missing make target, or AGENTS.md is not a symlink
 	@./scripts/skill-check.sh
 
 # Conventional Commits, which CLAUDE.md claimed CI enforced for a long

frontend/src/components/first-run-wizard/first-run-wizard.ts

@@ -2,14 +2,12 @@ import { LitElement, html, css, nothing } from 'lit';
 import { customElement, state, query } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/dialog/dialog.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
-import { EventsOn } from '@runtime/runtime';
 import {
     AddLibrary,
     GetAllLibrariesWithTrackCounts,
 } from '@go/library/library.js';
 import { describeError, explainError } from '@utils/describe-error';
 import { nameDialogsIn } from '@utils/name-dialog';
-import { Events } from '../../events';
 import { pickDirectory } from '../../utils/pick-directory';
 
 /**
@@ -21,13 +19,6 @@ import { pickDirectory } from '../../utils/pick-directory';
  * prompting the user to pick their music folder, registers it through the
  * library CRUD API, and dismisses itself.  AddLibrary emits LibraryAdded
  * and kicks off the initial scan automatically.
- *
- * **The dismissal follows the library existing, not the button being
- * pressed.** `AddLibrary` emits `LibraryAdded` whoever calls it, so the
- * wizard waits on the state it exists to wait for rather than on a step
- * in its own flow — a library arriving by any other route (Settings, a
- * direct call) leaves a full-screen modal up otherwise, intercepting
- * every pointer event.
  */
 @customElement('first-run-wizard')
 export class FirstRunWizard extends LitElement {
@@ -46,18 +37,9 @@ export class FirstRunWizard extends LitElement {
     /** Error message from a failed pick/save, if any. */
     @state() private errorMessage = '';
 
-    /** Unsubscribe from LibraryAdded, while this element is connected. */
-    private cancelLibraryAdded?: () => void;
-
     override async connectedCallback(): Promise<void> {
         super.connectedCallback();
 
-        // Subscribed before the read below, so a library arriving while
-        // that call is in flight is not answered with a stale empty list.
-        this.cancelLibraryAdded = EventsOn(Events.LibraryAdded, () => {
-            this.dismiss();
-        });
-
         try {
             const existing = await GetAllLibrariesWithTrackCounts();
 
@@ -72,8 +54,6 @@ export class FirstRunWizard extends LitElement {
             return;
         }
 
-        if (this.finished) return;
-
         this.active = true;
 
         await this.updateComplete;
@@ -81,13 +61,6 @@ export class FirstRunWizard extends LitElement {
         if (this.dialog) this.dialog.open = true;
     }
 
-    override disconnectedCallback(): void {
-        this.cancelLibraryAdded?.();
-        this.cancelLibraryAdded = undefined;
-
-        super.disconnectedCallback();
-    }
-
     static override styles = css`
         wa-dialog {
             --width: 480px;
@@ -266,20 +239,6 @@ export class FirstRunWizard extends LitElement {
         if (!this.finished) e.preventDefault();
     };
 
-    /**
-     * Close, and stay closed: a library exists, so setup is over.
-     *
-     * `finished` is set first, or `preventClose` cancels the hide this
-     * asks for.
-     */
-    private dismiss(): void {
-        this.finished = true;
-
-        if (this.dialog) this.dialog.open = false;
-
-        this.active = false;
-    }
-
     private handleChoose = async (): Promise<void> => {
         this.errorMessage = '';
 
@@ -305,7 +264,11 @@ export class FirstRunWizard extends LitElement {
         try {
             await AddLibrary(this.selectedDirectory);
 
-            this.dismiss();
+            this.finished = true;
+
+            if (this.dialog) this.dialog.open = false;
+
+            this.active = false;
         } catch (err) {
             this.errorMessage = explainError(
                 err,

frontend/test/components/first-run-wizard.test.ts

@@ -1,123 +0,0 @@
-/**
- * #175: the first-run wizard's dismissal follows the library existing,
- * not its own button being pressed.
- *
- * The wizard is a modal that blocks every pointer event, so a library
- * arriving by another route — Settings, a direct call — used to leave
- * it up over an app that was already set up. `LibraryAdded` is emitted
- * by `AddLibrary` whoever calls it, which is what makes one
- * subscription the whole fix.
- */
-import { beforeEach, describe, expect, it } from 'vitest';
-
-import { Events } from '../../src/events';
-import { emit, stub } from '../support/harness';
-import { fixture, shadow, shadowAll } from '../support/render';
-import { wails } from '../support/wails-fake';
-
-import '@components/first-run-wizard/first-run-wizard';
-
-import type { FirstRunWizard } from '@components/first-run-wizard/first-run-wizard';
-
-/** A library row, as `GetAllLibrariesWithTrackCounts` returns one. */
-const aLibrary = {
-    id: 1,
-    name: 'Music',
-    path: '/home/logan/Music',
-    trackCount: 9,
-};
-
-/** Mount the wizard on a fresh install: no libraries yet. */
-async function wizardOnAFreshInstall(): Promise<FirstRunWizard> {
-    stub('library.Library.GetAllLibrariesWithTrackCounts', []);
-
-    return fixture<FirstRunWizard>('first-run-wizard');
-}
-
-/** Whether the wizard is rendering its modal at all. */
-function isShowing(el: FirstRunWizard): boolean {
-    return shadow(el, 'wa-dialog') !== null;
-}
-
-beforeEach(() => {
-    stub('library.Library.AddLibrary', aLibrary);
-});
-
-describe('first-run-wizard', () => {
-    it('shows on a fresh install and stays up until a library exists', async () => {
-        const el = await wizardOnAFreshInstall();
-
-        expect(isShowing(el)).toBe(true);
-    });
-
-    it('stays hidden when a library is already configured', async () => {
-        stub('library.Library.GetAllLibrariesWithTrackCounts', [aLibrary]);
-
-        const el = await fixture<FirstRunWizard>('first-run-wizard');
-
-        expect(isShowing(el)).toBe(false);
-    });
-
-    it('dismisses when a library appears by another route', async () => {
-        const el = await wizardOnAFreshInstall();
-
-        expect(isShowing(el)).toBe(true);
-
-        emit(Events.LibraryAdded, aLibrary);
-        await el.updateComplete;
-
-        expect(isShowing(el)).toBe(false);
-    });
-
-    it('does not raise itself when a library arrives while it is asking', async () => {
-        // The read is still in flight when the event lands, so its
-        // answer — an empty list — is stale by the time it returns.
-        let answer: (libraries: unknown[]) => void = () => {};
-
-        stub(
-            'library.Library.GetAllLibrariesWithTrackCounts',
-            () =>
-                new Promise((resolve) => {
-                    answer = resolve;
-                }),
-        );
-
-        const el = await fixture<FirstRunWizard>('first-run-wizard');
-
-        emit(Events.LibraryAdded, aLibrary);
-        answer([]);
-
-        await el.updateComplete;
-        await new Promise((r) => setTimeout(r, 0));
-        await el.updateComplete;
-
-        expect(isShowing(el)).toBe(false);
-    });
-
-    it('still dismisses through its own Get Started button', async () => {
-        stub('frontendutil.FrontendUtil.HasNativeDirectoryPicker', true);
-        stub('frontendutil.FrontendUtil.DirectoryPicker', '/home/logan/Music');
-
-        const { resetDirectoryPickerCache } = await import(
-            '@utils/pick-directory'
-        );
-
-        resetDirectoryPickerCache();
-
-        const el = await wizardOnAFreshInstall();
-        const [choose, finish] = shadowAll<HTMLButtonElement>(el, '.btn');
-
-        choose?.click();
-        await new Promise((r) => setTimeout(r, 0));
-        await el.updateComplete;
-
-        finish?.click();
-        await new Promise((r) => setTimeout(r, 0));
-        await el.updateComplete;
-
-        expect(
-            wails.calls.filter((c) => c.path === 'library.Library.AddLibrary'),
-        ).toHaveLength(1);
-        expect(isShowing(el)).toBe(false);
-    });
-});

lefthook.yml

@@ -38,10 +38,14 @@ pre-commit:
       glob: "*.go"
       run: ./scripts/bindings-check.sh
 
-    # .pi/ documents make targets; a stale one sends an agent off a
-    # cliff with total confidence.  Instant.
+    # The docs document make targets; a stale one sends an agent — or a
+    # contributor reading CONTRIBUTING.md — off a cliff with total
+    # confidence.  The glob is the script's own scanned set, because a
+    # hook that does not fire on a file the check reads is the drift the
+    # check exists to prevent: it was `{Makefile,.pi/**/*.md}` while the
+    # script already read CLAUDE.md.  Instant.
     skill-check:
-      glob: "{Makefile,.pi/**/*.md}"
+      glob: "{Makefile,.pi/**/*.md,AGENTS.md,CLAUDE.md,README.md,CONTRIBUTING.md}"
       run: ./scripts/skill-check.sh
 
     frontend-typecheck:

scripts/skill-check.sh

@@ -14,6 +14,11 @@
 # missing: CLAUDE.md names 27 targets and nothing verified one of them,
 # so the file the agents trust most was the file least checked.
 #
+# README.md and CONTRIBUTING.md are in it too, and the header sentence
+# above is why: a person who has *not* read the Makefile goes looking in
+# the contributor-facing doc, so a renamed target sends them off the
+# same cliff it sends an agent off.  CONTRIBUTING.md names 21 targets.
+#
 # **AGENTS.md is a symlink to CLAUDE.md.**  This repo is worked on by
 # two agent harnesses that read different files by convention — Claude
 # Code reads CLAUDE.md, others read AGENTS.md — and two harnesses
@@ -43,7 +48,19 @@ if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
 	fi
 fi
 
-[ -d .pi ] || exit 0
+# The scan is over the docs that are actually there: a checkout without
+# .pi/ still has README.md and CONTRIBUTING.md to check, and gating the
+# whole run on .pi/ would have made the human-facing half conditional on
+# the agent-facing one.  This list is used twice — once to read the
+# mentions out and once to say which file a missing target came from —
+# because a second list is a second thing to forget.
+# `ls` exits non-zero when *any* of its arguments is missing while still
+# printing the ones that are there, and under `set -e` that would sink
+# the assignment rather than scanning what exists, so swallow it.
+docs="$({ find .pi -name '*.md' 2>/dev/null
+	ls CLAUDE.md README.md CONTRIBUTING.md 2>/dev/null || true; })"
+
+[ -n "$docs" ] || exit 0
 
 # `make -pq` prints the database including every rule, without running
 # anything.  It exits non-zero when a target is out of date, and under
@@ -68,7 +85,7 @@ targets="$({ make -pqRr 2>/dev/null || true; } |
 # AGENTS.md is deliberately not in this list: it is a symlink to
 # CLAUDE.md, asserted above, so scanning it would report every failure
 # twice under two names.
-mentioned="$({ find .pi -name '*.md' 2>/dev/null; echo CLAUDE.md; } |
+mentioned="$(printf '%s\n' "$docs" |
 	xargs awk '
 		FNR == 1 { fence = 0 }
 		/^```/   { fence = !fence; next }
@@ -93,10 +110,10 @@ for t in $mentioned; do
 done
 
 if [ -n "$missing" ]; then
-	echo "skill-check: the agent docs name make targets that do not exist:" >&2
+	echo "skill-check: the docs name make targets that do not exist:" >&2
 	for t in $missing; do
 		echo "  make $t" >&2
-		grep -rln "make $t" .pi CLAUDE.md --include='*.md' | sed 's/^/      /' >&2
+		printf '%s\n' "$docs" | xargs grep -ln "make $t" | sed 's/^/      /' >&2
 	done
 	echo "Fix the docs, or restore the target." >&2
 	exit 1