@estiva-app/ui 0.28.0 → 0.29.0

package/skill/estiva-ui.md

@@ -0,0 +1,126 @@
+# Search before you build
+
+Every screen here is built from parts: the package `@estiva-app/ui`, and each
+app's own. Every reusable part has a Storybook page that says when to use it
+and when not to. Most of what gets asked for already exists somewhere.
+
+## When this applies
+
+- Building or changing a screen, panel, list, row, header, dialog or menu.
+- Adding a component, or a new file that draws one.
+- Changing how something looks: its size, spacing, colour or type.
+
+## Steps, in order
+
+1. **Search before creating anything.** Run
+   `npm run ui:find <what it does, in plain words>` in the repository you are
+   in. Do it yourself; never ask the person to. With nothing else typed it
+   searches the package and every app beside it, and prints a Storybook link
+   for each match. Show the person what it found, with the links.
+   - From a folder that holds several repositories, run it inside any one of
+     them (`npm --prefix <repo> run ui:find <words>`): each searches them all.
+   - Search again in other words before deciding nothing fits: "list column",
+     then "scrolling list"; "panel header", then "title row".
+2. **If something fits, read its page before using it:** the link, or the
+   `.mdx` beside its file. Read its opening line, **When** and **When not**.
+   *When not* names the part to use instead.
+3. **If nothing fits, say so and ask.** Do not invent a component. Do not copy
+   one from another app either: say which app has it, and ask whether it
+   should move into the package.
+4. **Never hand-roll what the package owns.** Its parts own their behaviour:
+   keys, focus, floating, closing, scrolling, truncation. The editor gate
+   refuses a raw element, a rebuilt behaviour or a restyled part, and its error
+   names the part to use.
+5. **An exception** carries `// @estiva-escape: <reason>` on the line above
+   it. Never `eslint-disable`.
+
+## Gotchas
+
+The mistakes made here more than once, from the record (UIG-20 counted 542
+recorded defects; these 24 cover the 111 that are screen work). Each says what
+to do instead. Apps differ in frame and theme: never carry one app's layout,
+sizes or colours into another; take them from tokens.
+
+**Layout**
+
+1. **A header row drawn by hand** at the top of a column → `ContainerHeader`.
+   Its actions are `IconButton`s with tooltips. A whole list column is
+   `ListColumn`, which draws the bar; a field that adds to the list goes in its
+   `above`.
+2. **A list with no scroll container**, cut off at the fold (no lint sees a box
+   that was never built) → a list column is `ListColumn`, which scrolls its
+   rows; anything else that grows goes in a `ScrollArea`. Check with more rows
+   than fit.
+3. **`EmptyState` at the wrong level** → `scope="page"` only when the whole
+   page is empty, `scope="section"` for one part of it, placed inside the box
+   its rows live in. Never wrap it in a box of your own that places it.
+4. **`EditableText` rendering too large**: it has no size of its own and takes
+   the size around it → put the text size on your own element around it. The
+   same holds for `Person`, `Link`, `Card` and `SectionLabel`.
+5. **Flex rows that move things**: loose children of an `items-start` row float
+   at different heights; a scrolling flex column squashes rows → group them in
+   one `items-center` row; give your own rows in a scrolling column `shrink-0`.
+6. **A group heading drawn by hand** (a row holding a `SectionLabel`) →
+   `SectionHeader` (`hover="none"` when nothing acts on it); a group that folds
+   is `CollapsibleSection`.
+7. **A line drawn by hand** (`border-t`, `<hr>`, a gap) → `Divider`; between a
+   menu's groups, `MenuSeparator`, which brings its own room.
+
+**Parts and props**
+
+8. **The browser's tooltip** (`title=`), or an icon button with none →
+   `WithTooltip` (`inline` inside text) or `IconButton`'s `tooltip`.
+9. **A row of icon buttons laid out by hand** → `Toolbar` with `ToolbarButton`
+   and `ToolbarLink` (they throw outside one). A row inside a `Popover` is a
+   `Toolbar` with `surface={false}`.
+10. **Fields sent by a hand-written Enter handler**, with no form → `Form`,
+    which owns the keys, `busy` and focus. Clear a field's `error` when it
+    changes, or the form will not send.
+11. **A link to an in-app page as a bare `href`**: every click reloads the app
+    → go through the app's router, as `NavItem` does.
+12. **Wrong loading and failure states**: an `EmptyState` while data is still
+    coming, a hand-made pulsing box → a skeleton shaped like what is coming
+    (`SkeletonList`, `SkeletonRow`, `SkeletonBar`). Say a failure in
+    words, never as "empty" and never in red; a failure toast or banner has
+    the `error` tone.
+13. **A floating panel mounted only while open** (`{open && <Popover…>}`), or
+    capped with a class → keep it mounted and drive `open`; cap a long list with
+    `Popover`'s `maxHeight`; never open a panel around an empty list.
+14. **Deleting a part without checking what else it carried** → read everything
+    the container holds first, and remove its imports, escapes and stories with it.
+
+**Stories and usage pages**
+
+15. **A story that shows one branch**: something drawn behind `{prop && …}` that
+    no story passes, or data with no fixture → a story for every branch; one
+    fixture holding what the backend really sends. `estiva-ui check` refuses
+    the first.
+16. **A screen with no story** is where mistakes hide: every gate was green on
+    a page with eight → look at the running screen, or give it a story with
+    more rows than fit, an empty state and a loading state.
+17. **A story under a new heading, or named after its file** → use a heading
+    the Storybook already has, name the entry after its part, give each meta its
+    `component` (or the part's page a **Seen in** line).
+18. **`{…}` in a usage page's prose** (MDX reads it as code and the page will
+    not compile), or a description over two lines → backticks around braces; a
+    part's description is one line.
+
+**Working in these repositories**
+
+19. **An escape with a false reason** ("no part does this" has been wrong
+    twice) → search for the thing first. Write the escape on the line above
+    the statement, never inside `eslint-disable`.
+20. **Classes the lint cannot see**: in a const not named `…_CLASSES` or
+    `…Styles`, or in an array that is `.join()`ed → keep classes in
+    `className` or `cn()`, or in a map with one of those names.
+21. **The editor gate and this skill need a session started at the repository's
+    top folder.** Started elsewhere, run the repository's `lint:rules` yourself
+    before committing.
+22. **`npm install` on Windows prunes Linux-only entries from the lockfile**, and
+    CI dies at `npm ci` → never commit a lockfile Windows rewrote; restore it and
+    bump only the package's own entry. Stop every dev server before `npm ci`.
+23. **Storybook shows old code after a package bump** → delete
+    `node_modules/.cache/storybook` and restart.
+24. **A local checkout lags `origin/main`, and a conflicting PR shows no CI** →
+    `git fetch` and read `origin/main`; when checks are missing, look for a
+    conflict first.

package/src/gates/app-checks.ts

@@ -199,8 +199,14 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: "CI's job gate runs it", run: () => h.ciJob('gate', 'registry:check') },
       { what: 'the app keeps no copy of it in its own gates-checks.mjs', run: () => h.exists(at('scripts/gates-checks.mjs')) ? h.lacks(at('scripts/gates-checks.mjs'), '"When not"', 'the app checks no page sections itself') : h.PASS('the app has no gates-checks.mjs') },
     ]),
+    // The Claude skill (UIG-20): its text is the installed package's, read in by a
+    // loader `estiva-ui skill` writes; the app commits the loader and the settings.
     ticket('UIG-20', [
-      { what: 'a committed skill runs ui:find', run: () => (h.listFiles('.claude/skills', (n) => n === 'SKILL.md').some((f) => h.read(f).includes('ui:find')) ? h.PASS('a skill runs ui:find') : h.FAIL('no skill in .claude/skills runs ui:find')) },
+      { what: "the skill's loader reads the installed package's text", run: () => h.contains('.claude/skills/estiva-ui/SKILL.md', `!\`cat "\${CLAUDE_PROJECT_DIR}/${at('node_modules/@estiva-app/ui/skill/estiva-ui.md')}"\``, 'the loader reads the package’s skill') },
+      { what: 'the search runs without a prompt', run: () => h.contains('.claude/settings.json', 'Bash(npm run ui:find *)', '.claude/settings.json allows npm run ui:find') },
+      { what: 'ui:find searches every app beside this one: it names none', run: () => h.lacks(at('package.json'), /"ui:find":[^\n]*--also/, 'ui:find names no neighbour, so it finds them all') },
+      ...(WEB ? [{ what: 'ui:find runs from the top folder too', run: () => h.contains('package.json', /"ui:find":/, 'the top folder has ui:find') }] : []),
+      { what: "CI's job gate refuses a loader that differs", run: () => (h.exists(at('node_modules/@estiva-app/ui/dist/registry/cli.js')) && /claude skill:/.test(h.read(at('node_modules/@estiva-app/ui/dist/registry/cli.js'))) ? h.ciJob('gate', 'registry:check') : h.FAIL('the installed package does not check the loader: take a version that does')) },
     ]),
     ticket('UIG-21', [
       { what: 'path-scoped instructions exist', run: () => (h.listFiles('.claude/rules', (n) => n.endsWith('.md')).some((f) => /^paths:/m.test(h.read(f))) ? h.PASS('.claude/rules has paths: instructions') : h.FAIL('no .claude/rules file with paths:')) },

package/src/gates/create-app.test.ts

@@ -30,7 +30,7 @@ describe('create-estiva-app', () => {
   it('makes the frame, the checks and the gates, each as a file that imports the package', () => {
     expect(Object.keys(files).sort()).toEqual(
       [
-        '.claude/settings.json', '.env.example', '.gates-count.json', '.github/workflows/deploy.yml', '.gitignore', '.storybook/main.ts', '.storybook/preview.tsx',
+        '.claude/settings.json', '.claude/skills/estiva-ui/SKILL.md', '.env.example', '.gates-count.json', '.github/workflows/deploy.yml', '.gitignore', '.storybook/main.ts', '.storybook/preview.tsx',
         'CLAUDE.md', 'README.md', 'docs/GATES-DEBT.md', 'eslint.config.js', 'eslint.gates.config.js', 'eslint.tokens.config.js', 'index.html', 'package.json',
         'postcss.config.js', 'scripts/gates-checks.mjs', 'src/App.test.tsx', 'src/App.tsx', 'src/auth/AuthShell.tsx', 'src/auth/boot.ts', 'src/auth/estivaId.ts',
         'src/config.ts', 'src/index.css', 'src/main.tsx', 'src/pages/HomePage.stories.tsx', 'src/pages/HomePage.tsx',
@@ -41,6 +41,10 @@ describe('create-estiva-app', () => {
     expect(files['eslint.gates.config.js']).toContain("from '@estiva-app/ui/gates'")
     expect(files['scripts/gates-checks.mjs']).toContain("appChecks(h, { page: 'src/pages/HomePage.tsx' })")
     expect(JSON.parse(files['.claude/settings.json']).hooks.PreToolUse[0].hooks[0].command).toBe('node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook')
+    // The skill loads from the package's one copy: the app holds its trigger and the line that reads it (UIG-20).
+    expect(JSON.parse(files['.claude/settings.json']).permissions.allow).toContain('Bash(npm run ui:find *)')
+    expect(files['.claude/skills/estiva-ui/SKILL.md']).toContain('!`cat "${CLAUDE_PROJECT_DIR}/node_modules/@estiva-app/ui/skill/estiva-ui.md"`')
+    expect(files['.claude/skills/estiva-ui/SKILL.md']).not.toContain('## Steps')
   })
 
   it('uses the sidebar frame and one theme, set on <html>', () => {

package/src/gates/create-app.ts

@@ -35,6 +35,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { APP_RULE_IDS } from '../eslint/index'
+import { loaderText, SEARCH_RULES } from '../registry/skill'
 
 interface PackageJson {
   version: string
@@ -292,8 +293,12 @@ export default gateConfig({ quiet: { 'react-hooks': reactHooks } })
       hooks: {
         PreToolUse: [{ matcher: 'Edit|Write', hooks: [{ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook' }] }],
       },
+      permissions: { allow: SEARCH_RULES },
     }),
 
+    // The Claude skill (UIG-20): its trigger, and a line reading the installed package's text in.
+    '.claude/skills/estiva-ui/SKILL.md': loaderText(resolve('/app'), resolve('/app/node_modules/@estiva-app/ui')),
+
     'scripts/gates-checks.mjs': `import { appChecks } from '@estiva-app/ui/gates'
 
 /**

package/src/gates/gates.test.ts

@@ -178,6 +178,31 @@ describe('runHook', () => {
     }
   })
 
+  it('stops a new part once with what already exists, then lets it through (UIG-20)', async () => {
+    const seen = mkdtempSync(join(scratch, 'seen-'))
+    const input = { ...write('src/PanelHeader.tsx', 'export function PanelHeader() {\n  return <div>x</div>\n}\n'), session_id: 'one' }
+    const first = await runHook({ root: dir, input, seen })
+    expect(first.code).toBe(2)
+    expect(first.message).toContain('src/PanelHeader.tsx was not written yet: it adds a new part, PanelHeader.')
+    expect(first.message).toContain('What already exists for "panel header"')
+    expect(first.message).toContain('ContainerHeader')
+    expect((await runHook({ root: dir, input, seen })).code).toBe(0)
+    // Another session is asked again.
+    expect((await runHook({ root: dir, input: { ...input, session_id: 'two' }, seen })).code).toBe(2)
+    // The search reads every app beside this checkout: seconds on a machine that holds them all.
+  }, 60_000)
+
+  it('does not stop a file already there, a story, or a file that draws nothing', async () => {
+    const seen = mkdtempSync(join(scratch, 'seen-'))
+    for (const input of [
+      write('src/Page.tsx', 'export function Page() {\n  return <div>y</div>\n}\n'),
+      write('src/Panel.stories.tsx', 'export const Default = () => <div>x</div>\n'),
+      write('src/format.tsx', 'export function formatDate(date: Date) {\n  return date.toISOString()\n}\n'),
+    ]) {
+      expect((await runHook({ root: dir, input, seen })).code).toBe(0)
+    }
+  })
+
   it('finds the app in a folder of its own, as Ship keeps it in web/', async () => {
     const top = join(scratch, 'top')
     mkdirSync(top, { recursive: true })

package/src/gates/hook.ts

@@ -22,13 +22,24 @@
  * `replace_all` for Edit. An Edit carries no whole file, so the edit is applied
  * to the file on disk here. Anything it cannot read passes, and the tool itself
  * reports its own failure.
+ *
+ * **Search first** (UIG-20). A Write that would create a new file drawing a new
+ * part, and that the gate lets through, is stopped once: the hook runs
+ * `estiva-ui find` on the part's name and hands the matches back, so a session
+ * sees what already exists before it adds another. The same file written again
+ * in the same session goes through. The skill asks for the search; this makes
+ * sure it happened. A search that cannot run stops nothing.
  */
-import { existsSync, readFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import { isAbsolute, join, relative, resolve, sep } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { tmpdir } from 'node:os'
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import type { ESLint as ESLintClass } from 'eslint'
 import { countGates } from '../eslint/index'
+import { repositoryOf } from '../registry/skill'
 
 export interface HookOptions {
   /** The repository's top folder. Defaults to `$CLAUDE_PROJECT_DIR`, then the tool call's `cwd`. */
@@ -39,6 +50,8 @@ export interface HookOptions {
   audience?: 'app' | 'package'
   /** The hook's input, when not read from stdin (tests). */
   input?: unknown
+  /** Where a session's searches are remembered. Defaults to a folder in the system's temp. */
+  seen?: string
 }
 
 export interface HookResult {
@@ -50,13 +63,14 @@ export interface HookResult {
 
 interface ToolCall {
   tool_name?: string
+  session_id?: string
   cwd?: string
   tool_input?: { file_path?: unknown; content?: unknown; old_string?: unknown; new_string?: unknown; replace_all?: unknown }
 }
 
 const PASS: HookResult = { code: 0, message: '' }
 
-export async function runHook({ root, app = '.', audience = 'app', input }: HookOptions = {}): Promise<HookResult> {
+export async function runHook({ root, app = '.', audience = 'app', input, seen }: HookOptions = {}): Promise<HookResult> {
   let call: ToolCall
   try {
     call = (input ?? JSON.parse(readFileSync(0, 'utf8'))) as ToolCall
@@ -86,7 +100,7 @@ export async function runHook({ root, app = '.', audience = 'app', input }: Hook
   // the typecheck's to judge; the gate looks again at the edit that completes it.
   const errors = results.flatMap((r) => r.messages.filter((m) => m.severity === 2 && m.ruleId))
   const { disabled } = countGates(results)
-  if (errors.length === 0 && disabled.length === 0) return PASS
+  if (errors.length === 0 && disabled.length === 0) return searchFirst(call, file, text, appDir, top, seen) ?? PASS
 
   const shown = (p: string) => relative(top, p).split(sep).join('/')
   const lines = [`${shown(file)} was not written: the UI Guardrails refuse it (${shown(config)}).`]
@@ -96,6 +110,56 @@ export async function runHook({ root, app = '.', audience = 'app', input }: Hook
   return { code: 2, message: `${lines.join('\n')}\n` }
 }
 
+/** The part a Write would add in a new file, or null: a capitalised export, in a file that draws. */
+export function newPart(tool: string | undefined, file: string, text: string): string | null {
+  if (tool !== 'Write' || existsSync(file) || !file.endsWith('.tsx') || /\.stories\.tsx$/.test(file)) return null
+  if (!/<\/[A-Za-z]|\/>/.test(text)) return null
+  const named = /export\s+(?:default\s+)?(?:async\s+)?(?:function|const|class)\s+([A-Z][A-Za-z0-9]*)/.exec(text)?.[1]
+  if (named) return named
+  return /export\s+default\s+function\s*\(/.test(text) ? basename(file, '.tsx') : null
+}
+
+/** `PanelHeader` → `panel header`: the words the search is asked. */
+export const wordsOf = (name: string) => name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z])([A-Z][a-z])/g, '$1 $2').toLowerCase()
+
+/** The catalogue command: beside this file once built, or the built one from source (tests). */
+function findCommand(): string | null {
+  for (const at of ['../registry/cli.js', '../../dist/registry/cli.js']) {
+    const path = fileURLToPath(new URL(at, import.meta.url))
+    if (existsSync(path)) return path
+  }
+  return null
+}
+
+/** Stop a new part's first Write with what already exists; null lets it through. */
+function searchFirst(call: ToolCall, file: string, text: string, appDir: string, top: string, seen?: string): HookResult | null {
+  const part = newPart(call.tool_name, file, text)
+  const command = findCommand()
+  if (!part || !command) return null
+  const folder = seen ?? join(tmpdir(), 'estiva-ui-search-first')
+  const mark = join(folder, createHash('sha1').update(`${call.session_id ?? ''}\n${resolve(file)}`).digest('hex'))
+  if (existsSync(mark)) return null
+  const words = wordsOf(part)
+  const repo = basename(repositoryOf(appDir))
+  const run = spawnSync(process.execPath, [command, 'find', ...words.split(' '), '--root', appDir, '--repo', repo, '--limit', '5'], { encoding: 'utf8', timeout: 60_000 })
+  if (run.status !== 0 || !run.stdout.trim()) return null
+  try {
+    mkdirSync(folder, { recursive: true })
+    writeFileSync(mark, '')
+  } catch {
+    return null
+  }
+  const shown = relative(top, file).split(sep).join('/')
+  return {
+    code: 2,
+    message:
+      `${shown} was not written yet: it adds a new part, ${part}. Search before building (UIG-20). What already exists for "${words}":\n\n` +
+      `${run.stdout.trim()}\n\n` +
+      `If one of these does the job, use it, and read its page first. If the words were wrong, run \`npm run ui:find <other words>\`. ` +
+      `If nothing fits, tell the person, then write the file again: it goes through.\n`,
+  }
+}
+
 /** The file as it will be after this tool call, or null when that cannot be known. */
 function proposed(tool: string | undefined, args: NonNullable<ToolCall['tool_input']>, file: string): string | null {
   if (tool === 'Write') return typeof args.content === 'string' ? args.content : null

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)
 }