@estiva-app/ui 0.28.0 → 0.30.0

package/src/gates/token-lint.ts

@@ -89,6 +89,7 @@ const WORDS = {
     type: '$0 is type written by hand. A token from the package sets the size, line height, letter spacing and weight together (text-body-2, text-caption, text-h5...); if none fits, add one to the package, or say why not in an eslint-disable comment.',
     corner: '$0 is a corner written by hand, and no token has it. Use a corner from the package (rounded-sm 4px, rounded-md 6px, rounded-lg 8px...), or say why not in an eslint-disable comment.',
     shadow: '$0 is a shadow written by hand. Use a shadow from the package (shadow-sm, shadow-md, shadow-focus-ring, drop-shadow-glow-success...); a shadow with no token is a missing token.',
+    merge: "Merge classes with the package's cn(), which the app re-exports. A plain tailwind-merge does not know the type ramp, and drops text-body-2 beside a text colour.",
   },
   package: {
     ramp: "Tailwind's type ramp is not a token. Use the ramp in tailwind-preset.js: text-body-2, text-caption, text-h3, text-btn-default...",
@@ -98,6 +99,7 @@ const WORDS = {
     type: '$0 is type written by hand. A token from tailwind-preset.js sets the size, line height, letter spacing and weight together (text-body-2, text-caption, text-h5...); if none fits, add one to the preset and to cn.ts, or say why not in an eslint-disable comment.',
     corner: '$0 is a corner written by hand, and no token has it. Use a corner from tailwind-preset.js (rounded-sm 4px, rounded-md 6px, rounded-lg 8px...), or say why not in an eslint-disable comment.',
     shadow: '$0 is a shadow written by hand. Use a shadow from tailwind-preset.js (shadow-sm, shadow-md, shadow-focus-ring, drop-shadow-glow-success...); a shadow with no token is a missing token.',
+    merge: "Merge classes with this package's cn() (src/cn.ts), the one place tailwind-merge is taught the type ramp. A plain tailwind-merge drops text-body-2 beside a text colour.",
   },
 } satisfies Record<TokenAudience, Record<string, string>>
 
@@ -140,6 +142,9 @@ export function tokenLint({ tailwindConfig = 'tailwind.config.js', audience = 'a
           ],
         },
       ],
+      // UIG-21: "use the package's cn(), never a plain twMerge" was a sentence
+      // in all three repos' CLAUDE.md, and nothing checked it.
+      'no-restricted-imports': ['error', { paths: [{ name: 'tailwind-merge', message: words.merge }] }],
     },
   }
 }

package/src/registry/app.test.ts

@@ -526,6 +526,25 @@ describe('one search over the package and the apps', () => {
     expect(found.indexOf('estiva-ui:EmptyState')).toBeLessThan(found.indexOf('fixture:EmptyState'))
   })
 
+  it("puts a package part whose name carries a word before an app's part answering as many (UIG-20)", () => {
+    // "panel header" put an app's own `Header` above the package's `ContainerHeader`: its whole name is one of the words.
+    const header = buildAppRegistry({
+      root: app({ 'src/Header.tsx': '/** The top row of a panel: its title and its buttons. */\nexport function Header() {\n  return <header />\n}\n' }),
+      repo: 'fixture',
+    })
+    const found = findInRegistries([packageRegistry, header], 'panel header', { limit: 5 }).map((f) => `${f.entry.repo}:${f.entry.name}`)
+    expect(found[0]).toBe('estiva-ui:ContainerHeader')
+    expect(found).toContain('fixture:Header')
+  })
+
+  it("does not let a package part the words reach only through its notes bury the app's answer", () => {
+    const composer = buildAppRegistry({
+      root: app({ 'src/Composer.tsx': '/** Where a comment is written and sent. */\nexport function Composer() {\n  return <form />\n}\n' }),
+      repo: 'fixture',
+    })
+    expect(findInRegistries([packageRegistry, composer], 'comment composer')[0].entry).toMatchObject({ repo: 'fixture', name: 'Composer' })
+  })
+
   it('says which apps hand a package part on, and how a default is imported', () => {
     const text = formatFindings([packageRegistry, registry], findInRegistries([packageRegistry, registry], 'Button', { limit: 1 }), 'Button')
     expect(text).toContain('fixture hands it on from @/components/ui/Button')
@@ -554,10 +573,48 @@ describe.skipIf(!existsSync(cli))('estiva-ui in an app', () => {
     }
     expect(failed.stdout).toMatch(/^fixture: 17 parts in 15 files \(2 more hold none\)/)
     expect(failed.stderr).toContain('Timeline (reusable, src/components/Timeline.tsx) has no usage page: write src/components/Timeline.mdx')
-    const one = app({ 'src/One.tsx': '/** One, drawn once. */\nexport function One() {\n  return <i />\n}\n' })
+    const one = app({ 'src/One.tsx': '/** One, drawn once. */\nexport function One() {\n  return <i />\n}\n', 'node_modules/@estiva-app/ui/skill/estiva-ui.md': '# The skill\n' })
+    run(['skill'], one)
     expect(run(['check'], one)).toContain('usage pages: all 0 reusable parts keep the contract')
   })
 
+  it('skill writes a loader that reads the installed package, and check fails when it is missing or differs (UIG-20)', () => {
+    const two = app({ 'src/Two.tsx': '/** Two, drawn once. */\nexport function Two() {\n  return <i />\n}\n', 'node_modules/@estiva-app/ui/skill/estiva-ui.md': '# The skill\n' })
+    const failure = (cwd: string) => {
+      try {
+        run(['check'], cwd)
+      } catch (error) {
+        return (error as { stderr?: string }).stderr ?? ''
+      }
+      return ''
+    }
+    expect(failure(two)).toContain('.claude/skills/estiva-ui/SKILL.md is missing: run "estiva-ui skill" and commit it')
+    run(['skill'], two)
+    const loader = readFileSync(join(two, '.claude', 'skills', 'estiva-ui', 'SKILL.md'), 'utf8')
+    expect(loader).toMatch(/^---\nname: estiva-ui\ndescription: "Use before building/)
+    expect(loader).toContain('!`cat "${CLAUDE_PROJECT_DIR}/node_modules/@estiva-app/ui/skill/estiva-ui.md"`')
+    expect(JSON.parse(readFileSync(join(two, '.claude', 'settings.json'), 'utf8')).permissions.allow).toContain('Bash(npm run ui:find *)')
+    // Its text is the package's, never a copy.
+    expect(loader).not.toContain('# The skill')
+    expect(run(['check'], two)).toContain('claude skill: the loader reads the package’s text')
+    writeFileSync(join(two, '.claude', 'skills', 'estiva-ui', 'SKILL.md'), `${loader}\nA line of our own.\n`)
+    expect(failure(two)).toContain('SKILL.md is not what the package writes')
+  })
+
+  it('skill --out writes a loader for a folder that holds the repositories, reading an app inside it', () => {
+    const holder = mkdtempSync(join(tmpdir(), 'uig20-holder-'))
+    made.push(holder)
+    mkdirSync(join(holder, 'one', 'node_modules', '@estiva-app', 'ui', 'skill'), { recursive: true })
+    writeFileSync(join(holder, 'one', 'package.json'), JSON.stringify({ name: 'one' }))
+    writeFileSync(join(holder, 'one', 'node_modules', '@estiva-app', 'ui', 'skill', 'estiva-ui.md'), '# The skill\n')
+    run(['skill', '--out', '..'], join(holder, 'one'))
+    const loader = readFileSync(join(holder, '.claude', 'skills', 'estiva-ui', 'SKILL.md'), 'utf8')
+    expect(loader).toContain('!`cat "${CLAUDE_PROJECT_DIR}/one/node_modules/@estiva-app/ui/skill/estiva-ui.md"`')
+    // Claude Code refuses a path that climbs out with `..`, so a folder that does not hold the app is refused here.
+    const elsewhere = app({ 'node_modules/@estiva-app/ui/skill/estiva-ui.md': '# The skill\n' })
+    expect(() => run(['skill', '--out', holder], elsewhere)).toThrow(/does not hold/)
+  })
+
   it("find searches the app and the package, and never takes an app's own registry.json for the package's", () => {
     // What `estiva-ui build` leaves behind in an app, and git ignores.
     run(['build'], root)

package/src/registry/cli.ts

@@ -3,9 +3,10 @@
  * `estiva-ui` — the catalogue as a command (UIG-12, UIG-13; docs/GATES.md §23
  * for why it ships in the package rather than as a script pasted into each repo).
  *
- *   estiva-ui find <words…> [--also [name=]<folder>]… [--json] [--limit n]
+ *   estiva-ui find <words…> [--here | --also [name=]<folder>…] [--json] [--limit n]
  *   estiva-ui build [--out <path>]
  *   estiva-ui check
+ *   estiva-ui skill [--out <folder>]
  *
  * Every command takes `--root <folder>` (the library it reads; default: here)
  * and `--repo <name>` (what an app's entries are called; default: its package name).
@@ -21,15 +22,23 @@
  *
  * `find` searches the package's catalogue — the one shipped inside the installed
  * package, or this repo's own in the package — plus, in an app, the app's own,
- * built fresh, plus each `--also` app that sits beside it.
+ * built fresh, plus every app beside it (UIG-20, `./siblings`): found, not
+ * named, so one command answers the same from any repository, or from the
+ * folder that holds them. `--here` searches no neighbour; `--also` names them.
+ *
+ * `skill` writes the repository's Claude skill loader (UIG-20, `./skill`), or
+ * the one for `--out <folder>`; `check` fails when the repository's is missing
+ * or differs.
  */
 import { spawnSync } from 'node:child_process'
-import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { basename, join, resolve } from 'node:path'
+import { basename, dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { CONTRACT_KINDS, contractProblems, linkProblems } from './contract'
 import { findInRegistries, formatFindings } from './find'
+import { findSiblings, workspaceOf } from './siblings'
+import { loaderPath, loaderProblem, loaderText, repositoryOf, settingsPath, settingsWithSearch } from './skill'
 import { CLASSES, validateRegistry, type Registry } from './schema'
 
 /**
@@ -91,6 +100,20 @@ function readPackageRegistry(): Registry {
   return registry
 }
 
+/** The installed package whose skill text a loader reads: this repo in the package, else the app's install. */
+const packageRoot = () => (isPackage ? root : resolve(root, 'node_modules', '@estiva-app', 'ui'))
+
+/** The Claude skill loader (UIG-20): reports, and says whether it passed. */
+function checkLoader(): boolean {
+  const problem = loaderProblem(repositoryOf(root), packageRoot())
+  if (problem) {
+    process.stderr.write(`claude skill: ${problem}\n`)
+    return false
+  }
+  process.stdout.write('claude skill: the loader reads the package’s text\n')
+  return true
+}
+
 async function buildApp(folder: string, repo: string | undefined): Promise<Registry> {
   const { buildAppRegistry } = await appBuilder()
   const registry = buildAppRegistry({ root: folder, repo })
@@ -179,7 +202,13 @@ async function main(): Promise<number> {
           process.stderr.write(`not searched: ${first}${more.length ? `\n${more.slice(0, 3).join('\n')}${more.length > 3 ? `\n  …and ${more.length - 3} more — run "estiva-ui check" there` : ''}` : ''}\n`)
         }
       }
-      if (!isPackage) await add(root, value('repo'))
+      // The folder it runs in is searched when it is an app; the folder that
+      // holds the repositories is not one, and only its neighbours answer.
+      const here = !isPackage && existsSync(resolve(root, 'package.json')) ? (manifestAt(root).name ?? basename(root)) : null
+      if (here) await add(root, value('repo'))
+      if (!values('also').length && !flag('here')) {
+        for (const sibling of findSiblings(workspaceOf(root), { skip: here ? [here] : [] })) await add(sibling.folder, sibling.name)
+      }
       for (const also of values('also')) {
         const [name, folder] = also.includes('=') ? [also.slice(0, also.indexOf('=')), also.slice(also.indexOf('=') + 1)] : [undefined, also]
         const at = resolve(root, folder)
@@ -236,7 +265,8 @@ async function main(): Promise<number> {
         }
         const linked = checkLinks(registry, root)
         const shown = await checkGated(registry, root)
-        return broken.length || !linked || !shown ? 1 : 0
+        const loaded = checkLoader()
+        return broken.length || !linked || !shown || !loaded ? 1 : 0
       }
       const { buildRegistry, serializeRegistry } = await packageBuilder()
       const path = packageRegistryPath()
@@ -259,11 +289,33 @@ async function main(): Promise<number> {
       process.stdout.write(`${path}: current, ${built.entries.length} entries from ${built.builtFrom.exports} exports\n`)
       const linked = checkLinks(built, root)
       const shown = await checkGated(built, root, ['component'])
-      return linked && shown ? 0 : 1
+      const loaded = checkLoader()
+      return linked && shown && loaded ? 0 : 1
+    }
+
+    case 'skill': {
+      const out = value('out')
+      const folder = out ? resolve(out) : repositoryOf(root)
+      // The loader's path starts where the session does and cannot climb out:
+      // Claude Code refuses a `..` in it.
+      if (relative(folder, packageRoot()).startsWith('..')) {
+        process.stderr.write(`${folder} does not hold ${packageRoot()}: a loader there could not reach the skill's text\n`)
+        return 1
+      }
+      const path = loaderPath(folder)
+      mkdirSync(dirname(path), { recursive: true })
+      writeFileSync(path, loaderText(folder, packageRoot()), 'utf8')
+      process.stdout.write(`${path}: the Claude skill, read from ${packageRoot()}\n`)
+      const settings = settingsWithSearch(folder)
+      if (settings) {
+        writeFileSync(settingsPath(folder), settings, 'utf8')
+        process.stdout.write(`${settingsPath(folder)}: the search allowed without a prompt\n`)
+      }
+      return 0
     }
 
     default:
-      process.stderr.write('estiva-ui <find | build | check>\n')
+      process.stderr.write('estiva-ui <find | build | check | skill>\n')
       return 1
   }
 }

package/src/registry/find.ts

@@ -96,6 +96,11 @@ export function findInRegistry(registry: Registry, query: string, { limit = 5 }:
  * An app's pass-on is not a result of its own — it is the package's part, and
  * the package's entry answers for it, saying which apps hand it on. At the
  * same strength the package's part comes first: it is the one to reach for.
+ * And a package part whose name carries one of the words comes before an app's
+ * part answering as many words, whatever each scored: "panel header" put an
+ * app's own `Header`, whose whole name is one of the words, above the package's
+ * `ContainerHeader` (UIG-20). Only by name: a package part the words reach
+ * through its notes alone would bury the app part that is the answer.
  */
 export function findInRegistries(registries: Registry[], query: string, { limit = 5 }: { limit?: number } = {}): Finding[] {
   const all = words(query)
@@ -162,7 +167,11 @@ export function findInRegistries(registries: Registry[], query: string, { limit
   }
 
   const fromPackage = (finding: Finding) => (finding.entry.app === null ? 0 : 1)
-  findings.sort((a, b) => b.matched - a.matched || b.score - a.score || fromPackage(a) - fromPackage(b) || a.entry.name.localeCompare(b.entry.name))
+  const namedInPackage = (finding: Finding) => (finding.entry.app === null && finding.where.includes('name') ? 0 : 1)
+  findings.sort(
+    (a, b) =>
+      b.matched - a.matched || namedInPackage(a) - namedInPackage(b) || b.score - a.score || fromPackage(a) - fromPackage(b) || a.entry.name.localeCompare(b.entry.name),
+  )
   return findings.slice(0, limit)
 }
 

package/src/registry/siblings.test.ts

@@ -0,0 +1,85 @@
+/// <reference types="node" />
+/**
+ * UIG-20: the apps beside this one, found rather than named. The folder below
+ * is the shape of the real one: two apps (one inside a `web/` folder), a
+ * service that does not install the package, a worktree and somebody's copy of
+ * an app, and the package itself.
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, describe, expect, it } from 'vitest'
+import { appName, findSiblings, workspaceOf } from './siblings'
+
+const workspace = mkdtempSync(join(tmpdir(), 'uig20-'))
+afterAll(() => rmSync(workspace, { recursive: true, force: true }))
+
+const UI = { '@estiva-app/ui': '^0.28.0' }
+function put(path: string, text: string) {
+  mkdirSync(dirname(join(workspace, path)), { recursive: true })
+  writeFileSync(join(workspace, path), text)
+}
+function appAt(folder: string, name: string, deps: Record<string, string> = UI, part = 'Part') {
+  put(`${folder}/package.json`, JSON.stringify({ name, dependencies: deps }))
+  put(`${folder}/src/${part}.tsx`, `/** The ${part.toLowerCase()} of ${name}. */\nexport function ${part}() {\n  return <i />\n}\n`)
+}
+// A repository is a folder with `.git`: a directory, or a worktree's file.
+appAt('alpha', 'alpha-app', UI, 'Tabletop')
+put('alpha/.git/HEAD', 'ref: refs/heads/main\n')
+put('beta/package.json', JSON.stringify({ name: 'beta' }))
+put('beta/.git/HEAD', 'ref: refs/heads/main\n')
+appAt('beta/web', 'beta-web', { ...UI }, 'Workbench')
+appAt('alpha-copy', 'alpha-app')
+put('alpha-copy/.git', 'gitdir: ../alpha/.git/worktrees/alpha-copy\n')
+appAt('beta-notes/web', 'beta-web')
+appAt('service', 'service', { react: '^19.0.0' })
+put('ui/package.json', JSON.stringify({ name: '@estiva-app/ui' }))
+mkdirSync(join(workspace, 'ui', 'src'), { recursive: true })
+
+describe('the apps beside this one', () => {
+  it('is an app only when it installs the package and has a src', () => {
+    expect(appName(join(workspace, 'alpha'))).toBe('alpha-app')
+    expect(appName(join(workspace, 'service'))).toBeNull()
+    expect(appName(join(workspace, 'ui'))).toBeNull()
+    expect(appName(join(workspace, 'beta'))).toBeNull()
+  })
+
+  it('finds the folder that holds the repositories, from inside one or from that folder itself', () => {
+    expect(workspaceOf(join(workspace, 'beta', 'web', 'src'))).toBe(workspace)
+    expect(workspaceOf(join(workspace, 'alpha-copy'))).toBe(workspace)
+  })
+
+  it('finds each app once, inside a web folder too, and never a second checkout of the same app', () => {
+    expect(findSiblings(workspace).map((s) => [s.name, s.packageName])).toEqual([
+      ['alpha', 'alpha-app'],
+      ['beta', 'beta-web'],
+    ])
+  })
+
+  it('leaves out the app the search runs in, so a worktree of it is not searched twice', () => {
+    expect(findSiblings(workspace, { skip: ['alpha-app'] }).map((s) => s.name)).toEqual(['beta'])
+  })
+})
+
+// The command, as a session runs it: `dist/` is what `npm test` builds first.
+const cli = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'dist', 'registry', 'cli.js')
+describe.skipIf(!existsSync(cli))('estiva-ui find, with nothing else typed', () => {
+  const find = (cwd: string, ...words: string[]) =>
+    execFileSync(process.execPath, [cli, 'find', ...words], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+
+  it('searches every app beside the one it runs in', () => {
+    const out = find(join(workspace, 'alpha-copy'), 'workbench')
+    expect(out).toMatch(/^Workbench {2}· .* · {2}beta/m)
+  })
+
+  it('answers the same from the folder that holds them', () => {
+    expect(find(workspace, 'tabletop')).toMatch(/^Tabletop {2}· .* · {2}alpha/m)
+    expect(find(workspace, 'zzqqx')).toContain('Nothing in estiva-ui, alpha, beta matches')
+  })
+
+  it('searches no neighbour when told --here', () => {
+    expect(find(join(workspace, 'alpha'), 'workbench', '--here')).not.toContain('Workbench')
+  })
+})

package/src/registry/siblings.ts

@@ -0,0 +1,96 @@
+/// <reference types="node" />
+/**
+ * The apps beside this one, found rather than named (UIG-20).
+ *
+ * `estiva-ui find` with nothing else typed searches the package, the app it is
+ * run in, and every app that sits beside it. Katerina's condition for having no
+ * shared Storybook is that one search, run unasked from any repository, covers
+ * every catalogue; a list of names written into each repository's script would
+ * be the drifting copy the gates exist to remove, and would miss the next app.
+ *
+ * An app is a folder, or one folder inside it, whose `package.json` depends on
+ * `@estiva-app/ui` and which has a `src` to read. A service that does not
+ * install the package is not an app of this catalogue until it does.
+ *
+ * Each app is searched once. A second checkout of the same app (a worktree, or
+ * somebody's copy) carries the same package name; the app the search runs in
+ * wins, then the one whose top folder has the shortest name.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+
+export const PACKAGE_NAME = '@estiva-app/ui'
+
+export interface Sibling {
+  /** What its entries are called: its top folder's name. */
+  name: string
+  /** The folder the catalogue is built from. */
+  folder: string
+  /** Its `package.json` name, which says two checkouts are one app. */
+  packageName: string
+}
+
+function manifest(folder: string): { name?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> } | null {
+  const file = join(folder, 'package.json')
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** The name of the app in `folder`, or null when the folder is not one. */
+export function appName(folder: string): string | null {
+  const m = manifest(folder)
+  if (!m || m.name === PACKAGE_NAME) return null
+  const uses = Boolean(m.dependencies?.[PACKAGE_NAME] ?? m.devDependencies?.[PACKAGE_NAME])
+  return uses && existsSync(join(folder, 'src')) ? (m.name ?? basename(folder)) : null
+}
+
+const isDir = (path: string) => {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The folder that holds the repositories: the parent of the repository `from`
+ * is in, or `from` itself when it is in none (a folder that only holds them).
+ */
+export function workspaceOf(from: string): string {
+  let at = resolve(from)
+  for (;;) {
+    if (existsSync(join(at, '.git'))) return dirname(at)
+    const up = dirname(at)
+    if (up === at) return resolve(from)
+    at = up
+  }
+}
+
+/** Every app in `workspace`, one per package name, except those named in `skip`. */
+export function findSiblings(workspace: string, { skip = [] }: { skip?: string[] } = {}): Sibling[] {
+  let tops: string[]
+  try {
+    tops = readdirSync(workspace).filter((name) => !name.startsWith('.') && name !== 'node_modules' && isDir(join(workspace, name)))
+  } catch {
+    return []
+  }
+  const found: Sibling[] = []
+  for (const top of tops) {
+    const folder = join(workspace, top)
+    const inside = readdirSync(folder).filter((name) => !name.startsWith('.') && name !== 'node_modules' && isDir(join(folder, name)))
+    for (const candidate of [folder, ...inside.map((name) => join(folder, name))]) {
+      const packageName = appName(candidate)
+      if (packageName) found.push({ name: top, folder: candidate, packageName })
+    }
+  }
+  const byPackage = new Map<string, Sibling>()
+  for (const sibling of found.sort((a, b) => a.name.length - b.name.length || a.name.localeCompare(b.name))) {
+    if (skip.includes(sibling.packageName) || byPackage.has(sibling.packageName)) continue
+    byPackage.set(sibling.packageName, sibling)
+  }
+  return [...byPackage.values()].sort((a, b) => a.name.localeCompare(b.name))
+}

package/src/registry/skill.test.ts

@@ -0,0 +1,96 @@
+/// <reference types="node" />
+/**
+ * UIG-20: the skill's text, held to what it points at.
+ *
+ * The skill names the package's parts and props. Renaming one would leave the
+ * skill sending sessions to something that is not there, so every part it names
+ * is checked against the catalogue. Its Gotchas stand for recorded defects,
+ * reconciled in `docs/GATES-SKILL.md`; that table has to keep adding up.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import type { Registry } from './schema'
+import { loaderText, SKILL_DESCRIPTION } from './skill'
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const text = readFileSync(join(repoRoot, 'skill', 'estiva-ui.md'), 'utf8').replace(/\r\n/g, '\n')
+const registry = JSON.parse(readFileSync(join(repoRoot, 'registry.json'), 'utf8')) as Registry
+const byName = new Map(registry.entries.map((entry) => [entry.name, entry]))
+const record = readFileSync(join(repoRoot, 'docs', 'GATES-SKILL.md'), 'utf8').replace(/\r\n/g, '\n')
+
+describe('the skill', () => {
+  it('has the four parts, stays short, and fits Claude Code’s description limit', () => {
+    expect(text).toMatch(/^# /)
+    for (const heading of ['## When this applies', '## Steps, in order', '## Gotchas']) expect(text).toContain(heading)
+    expect(text.split('\n').length).toBeLessThan(200)
+    expect(SKILL_DESCRIPTION.length).toBeLessThanOrEqual(1536)
+    expect(text).toMatch(/1\. \*\*Search before creating anything\.\*\* Run\n {3}`npm run ui:find/)
+  })
+
+  it('names only parts the package has', () => {
+    const named = [...new Set([...text.matchAll(/`([A-Z][A-Za-z]+)`/g)].map((m) => m[1]))]
+    expect(named.length).toBeGreaterThan(20)
+    expect(named.filter((name) => !byName.has(name))).toEqual([])
+  })
+
+  it('names only props those parts have', () => {
+    const props: [string, string][] = [
+      ['EmptyState', 'scope'],
+      ['ListColumn', 'above'],
+      ['IconButton', 'tooltip'],
+      ['SectionHeader', 'hover'],
+      ['WithTooltip', 'inline'],
+      ['Toolbar', 'surface'],
+      ['Form', 'busy'],
+      ['Popover', 'maxHeight'],
+      ['Popover', 'open'],
+    ]
+    for (const [part, prop] of props) expect(byName.get(part)?.props.map((p) => p.name), `${part}.${prop}`).toContain(prop)
+  })
+
+  it('carries the four regressions the ticket names', () => {
+    expect(text).toMatch(/header row drawn by hand[\s\S]*?`ContainerHeader`/)
+    expect(text).toMatch(/no scroll container[\s\S]*?`ListColumn`/)
+    expect(text).toMatch(/`EditableText` rendering too large/)
+    expect(text).toMatch(/`EmptyState` at the wrong level[\s\S]*?scope="page"/)
+  })
+
+  it('assumes no app: no app is named, so it holds in every one', () => {
+    expect(`${text}\n${SKILL_DESCRIPTION}`).not.toMatch(/\b(Peek|Ship|Leaf)\b/)
+  })
+
+  it('is read in by the loader, never copied into it', () => {
+    const loader = loaderText(repoRoot, repoRoot)
+    expect(loader).not.toContain('## Gotchas')
+    expect(loader).toContain('!`cat "${CLAUDE_PROJECT_DIR}/skill/estiva-ui.md"`')
+  })
+})
+
+describe('the Gotchas, against the record', () => {
+  const rows = [...record.matchAll(/^\| (\d+) \|.*\| (G\d+|EXCL)\b[^|]*\|$/gm)].map((m) => ({ n: Number(m[1]), verdict: m[2] }))
+  const gotchas = [...text.matchAll(/^(\d+)\. \*\*/gm)].map((m) => Number(m[1]))
+
+  it('gives every recorded defect a row, numbered without a gap', () => {
+    expect(rows.length).toBeGreaterThan(500)
+    expect(rows.map((row) => row.n)).toEqual(rows.map((_, i) => i + 1))
+  })
+
+  it('backs every Gotcha with at least two recorded defects, and points at none the skill lacks', () => {
+    const numbered = gotchas.filter((n, i) => i >= 5 || n > 5) // the five steps are numbered too
+    const count = (g: number) => rows.filter((row) => row.verdict === `G${g}`).length
+    for (let g = 1; g <= 24; g++) expect(count(g), `G${g}`).toBeGreaterThanOrEqual(2)
+    expect(rows.filter((row) => row.verdict.startsWith('G') && Number(row.verdict.slice(1)) > 24)).toEqual([])
+    expect(numbered.filter((n) => n >= 1 && n <= 24).length).toBeGreaterThanOrEqual(19)
+    expect(text).toMatch(/^24\. \*\*/m)
+  })
+
+  it('states counts that add up', () => {
+    const into = rows.filter((row) => row.verdict !== 'EXCL').length
+    const out = rows.filter((row) => row.verdict === 'EXCL').length
+    expect(record).toContain(`**${rows.length}** | **${into}** | **${out}**`)
+    expect(text).toContain(`counted ${rows.length}`)
+    expect(text).toContain(`cover the ${into}`)
+  })
+})

package/src/registry/skill.ts

@@ -0,0 +1,117 @@
+/// <reference types="node" />
+/**
+ * The Claude skill (UIG-20): search the catalogue before building anything.
+ *
+ * Its text lives once, in this package, as `skill/estiva-ui.md` (Katerina,
+ * 17 September 2026: the same gate text pasted into two repositories is a
+ * defect). Claude Code only loads a skill from a `SKILL.md` under a folder's
+ * `.claude/skills/`, and no plugin source can point into `node_modules`, so each
+ * repository commits a loader: the trigger below, and one line that reads the
+ * installed package's text into the skill when it opens (`` !`…` `` runs before
+ * Claude sees the skill). `estiva-ui skill` writes it; `estiva-ui check` fails
+ * when a repository's loader is missing or is not what this writes.
+ *
+ * Measured with fresh sessions of Claude Code 2.1.215 (UIG-20), three things
+ * shape that line and the settings beside it:
+ *
+ * - An injected command runs without a prompt only when Claude Code can read it
+ *   statically as read-only: a plain `cat` of a plain path. A path with `..`
+ *   ("may follow a symlink outside the working directory"), a `$(…)`, or a
+ *   `node -e` are all refused, and a refused command stops the skill opening.
+ *   So the path starts at `${CLAUDE_PROJECT_DIR}`, the folder the session
+ *   started in, as the editor gate's hook does: a session started above or
+ *   below the repository gets neither.
+ * - An `allowed-tools` line makes opening the skill itself ask for permission
+ *   ("Execute skill"). So the search is allowed in the repository's committed
+ *   `.claude/settings.json` instead, and the skill carries no `allowed-tools`.
+ * - Claude reads a skill's description before it opens the skill, so the
+ *   trigger is written into the loader; it is the one part that cannot be
+ *   pulled in later.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+
+export const SKILL_NAME = 'estiva-ui'
+
+/** When Claude opens the skill by itself. Kept under Claude Code's 1,536 characters. */
+export const SKILL_DESCRIPTION =
+  'Use before building, adding or changing anything on screen in an app that uses @estiva-app/ui, or in @estiva-app/ui itself: ' +
+  'a screen, panel, list, row, header, dialog, menu, empty state, a new component, or how something looks. ' +
+  'Also when someone asks for a component in plain words ("I need a…", "add a…", "is there a…"). ' +
+  "It searches every catalogue at once, the package's and each app's Storybook, for a part that already does the job, " +
+  'and lists the mistakes this codebase keeps making.'
+
+/** The search, allowed without a prompt in the folder's committed `.claude/settings.json`. */
+export const SEARCH_RULES = ['Bash(npm run ui:find *)', 'Bash(npm --prefix * run ui:find *)', 'PowerShell(npm run ui:find *)', 'PowerShell(npm --prefix * run ui:find *)']
+
+/** The skill's text, inside a package folder. */
+export const skillTextPath = (packageRoot: string) => join(packageRoot, 'skill', `${SKILL_NAME}.md`)
+
+/** Where a folder keeps its loader. */
+export const loaderPath = (folder: string) => join(folder, '.claude', 'skills', SKILL_NAME, 'SKILL.md')
+
+/** Where a folder keeps the settings that allow the search. */
+export const settingsPath = (folder: string) => join(folder, '.claude', 'settings.json')
+
+/** The loader for `folder`, reading the text from `packageRoot`, from where a session in `folder` starts. */
+export function loaderText(folder: string, packageRoot: string): string {
+  const fromTop = relative(folder, skillTextPath(packageRoot)).split(sep).join('/')
+  return [
+    '---',
+    `name: ${SKILL_NAME}`,
+    `description: ${JSON.stringify(SKILL_DESCRIPTION)}`,
+    '---',
+    '',
+    '<!-- Written by `estiva-ui skill` from @estiva-app/ui; `estiva-ui check` fails when it differs. The text is the installed package’s, read in below. -->',
+    '',
+    `!\`cat "\${CLAUDE_PROJECT_DIR}/${fromTop}"\``,
+    '',
+  ].join('\n')
+}
+
+type Settings = { permissions?: { allow?: string[] } & Record<string, unknown> } & Record<string, unknown>
+
+const readSettings = (folder: string): Settings | null => {
+  const path = settingsPath(folder)
+  if (!existsSync(path)) return {}
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Settings
+  } catch {
+    return null
+  }
+}
+
+/** `folder`'s settings with the search allowed, everything else as it was; null when they cannot be read. */
+export function settingsWithSearch(folder: string): string | null {
+  const settings = readSettings(folder)
+  if (!settings) return null
+  const allow = settings.permissions?.allow ?? []
+  const missing = SEARCH_RULES.filter((rule) => !allow.includes(rule))
+  if (!missing.length && existsSync(settingsPath(folder))) return null
+  settings.permissions = { ...settings.permissions, allow: [...allow, ...missing] }
+  return `${JSON.stringify(settings, null, 2)}\n`
+}
+
+/** The repository `from` is in: the nearest folder with `.git`, or `from` when there is none. */
+export function repositoryOf(from: string): string {
+  let at = resolve(from)
+  for (;;) {
+    if (existsSync(join(at, '.git'))) return at
+    const up = dirname(at)
+    if (up === at) return resolve(from)
+    at = up
+  }
+}
+
+/** What is wrong with `folder`'s loader, or null when it is what `loaderText` writes. */
+export function loaderProblem(folder: string, packageRoot: string): string | null {
+  const path = loaderPath(folder)
+  const shown = relative(process.cwd(), path).split(sep).join('/') || path
+  if (!existsSync(path)) return `${shown} is missing: run "estiva-ui skill" and commit it`
+  if (readFileSync(path, 'utf8').replace(/\r\n/g, '\n') !== loaderText(folder, packageRoot)) return `${shown} is not what the package writes: run "estiva-ui skill" and commit it`
+  if (!existsSync(skillTextPath(packageRoot))) return `${shown} reads ${skillTextPath(packageRoot)}, which is not there`
+  const allow = readSettings(folder)?.permissions?.allow ?? []
+  const missing = SEARCH_RULES.filter((rule) => !allow.includes(rule))
+  if (missing.length) return `.claude/settings.json does not allow the search (${missing.join(', ')}): run "estiva-ui skill" and commit it`
+  return null
+}