@astryxdesign/cli 0.7.2-canary.ebcc404 → 0.7.2-canary.f2b60a0

package/api/search/search.domain-priority.test.mjs

@@ -75,14 +75,75 @@ async function placedGuides(route, seen = new Set()) {
 }
 
 describe('search domain priority — the rule', () => {
-  it('gives a doc no priority for a keyword or heading match', () => {
+  it('gives a doc no priority for a heading match or a one-word keyword', () => {
     const topic = {
       domain: 'doc',
       name: 'typography/font-setup',
-      keywords: ['font size'],
+      keywords: ['size'],
       titles: ['Font Setup', 'Font Sizes'],
     };
     expect(priority('font size', topic)).toBe(0);
+    expect(priority('size', topic)).toBe(0);
+  });
+
+  it('gives a doc priority when the query is one of its declared keywords', () => {
+    const guide = {
+      domain: 'doc',
+      name: 'guides/quality',
+      titles: ['Is my code good?'],
+      keywords: ['code review', 'review my code'],
+      _declared: ['code review', 'review my code'],
+    };
+    expect(priority('code review', guide)).toBe(1);
+    expect(priority('Code Reviews', guide)).toBe(1);
+    expect(priority('review my code', guide)).toBe(1);
+    // A section's keywords are its headings and code terms.
+    const section = {
+      ...guide,
+      name: 'before-you-ship',
+      _topic: 'guides/quality',
+      _section: 'before-you-ship',
+    };
+    expect(priority('code review', section)).toBe(0);
+  });
+
+  it("gives a doc no priority for a code term or table cell it didn't declare", () => {
+    // A typed doc's keywords hold the first column of its tables and the code
+    // terms its text mentions; `missing_field` reads as two words.
+    const reference = {
+      domain: 'doc',
+      name: 'cli/api/functions/validate-integration',
+      titles: ['validateIntegration'],
+      keywords: ['validate-integration', 'missing_field', 'file required'],
+      _declared: [],
+      _topic: 'cli/api/functions/validate-integration',
+    };
+    expect(priority('missing field', reference)).toBe(0);
+    expect(priority('file required', reference)).toBe(0);
+    expect(
+      priority('missing field', {...reference, _declared: ['missing field']}),
+    ).toBe(1);
+  });
+
+  it('keeps a component the query names exactly above a doc that declares it', async () => {
+    const tokens = tokenizeQuery('empty state');
+    const component = {domain: 'component', name: 'EmptyState'};
+    const doc = {
+      domain: 'doc',
+      name: 'illustrations',
+      keywords: ['empty state'],
+      _declared: ['empty state'],
+    };
+    const c = scoreQuery('empty state', tokens, component);
+    const d = scoreQuery('empty state', tokens, doc);
+    expect(
+      domainPriority('empty state', tokens, /** @type {any} */ (component), c),
+    ).toBe(1);
+    expect(
+      domainPriority('empty state', tokens, /** @type {any} */ (doc), d),
+    ).toBe(1);
+    // Both have priority, so the stronger match wins: the exact name.
+    expect(c?.score).toBeGreaterThan(d?.score ?? 0);
   });
 
   it('gives a doc priority when the query names it', () => {
@@ -190,32 +251,61 @@ describe('search domain priority — the rule', () => {
 
 describe('search domain priority — real docs and components', () => {
   it(
-    'finds the Text component before the typography guides for `font size`',
+    'finds a guide that declares the whole phrase above a component that matches one word',
     async () => {
-      for (const q of ['font size', 'font weight']) {
-        const results = (await search(q, {cwd})).data.results;
-        expect(results[0], q).toMatchObject({
-          domain: 'component',
-          name: 'Text',
-        });
-        const guide = results.findIndex(
-          r => r.domain === 'doc' && /^typography(?:\/|$)/.test(r.name),
-        );
-        // The guide still matches, below the component.
-        expect(guide, q).toBeGreaterThan(0);
+      const results = (await search('font size', {cwd})).data.results;
+      expect(results[0]).toMatchObject({domain: 'doc'});
+      expect(results[0].name).toMatch(/^typography(?:\/|$)/);
+      // The component the phrase points to stays near the top.
+      expect(
+        results
+          .slice(0, 3)
+          .some(r => r.domain === 'component' && r.name === 'Text'),
+      ).toBe(true);
+    },
+    SLOW,
+  );
+
+  it(
+    'keeps a component above a reference doc whose table or code terms hold the phrase',
+    async () => {
+      for (const q of ['missing field', 'file required']) {
+        const [top] = (await search(q, {cwd})).data.results;
+        expect(top, q).toMatchObject({domain: 'component', name: 'Field'});
       }
     },
     SLOW,
   );
 
   it(
-    'reports the text-match score unchanged',
+    'opens the guide that answers a declared phrase, not one that only mentions it',
+    async () => {
+      const [layers] = (await search('cascade layers', {cwd})).data.results;
+      expect(layers).toMatchObject({
+        domain: 'doc',
+        name: 'migration/migration-setup',
+      });
+      const [keyboard] = (await search('keyboard navigation', {cwd})).data
+        .results;
+      expect(keyboard?.name).not.toBe('migration/migration-verification');
+    },
+    SLOW,
+  );
+
+  it(
+    'keeps a component above docs that match only by a heading, with scores unchanged',
     async () => {
       const results = (await search('font size', {cwd})).data.results;
-      const guide = results.find(
-        r => r.domain === 'doc' && /^typography(?:\/|$)/.test(r.name),
+      const text = results.findIndex(
+        r => r.domain === 'component' && r.name === 'Text',
       );
-      expect(guide?.score).toBeGreaterThan(results[0].score);
+      expect(text).toBeGreaterThanOrEqual(0);
+      // A doc below Text outscores it on text alone: priority moved it, not the score.
+      expect(
+        results
+          .slice(text + 1)
+          .some(r => r.domain === 'doc' && r.score > results[text].score),
+      ).toBe(true);
     },
     SLOW,
   );

package/api/search/search.integration-check.test.mjs

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A reader looking for the check a build runs finds
+ * `astryx integration check` first.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {search} from './search.mjs';
+
+describe('search finds integration check for CI', () => {
+  it.each([
+    'ci',
+    'continuous integration',
+    'typecheck integration',
+    'integration check',
+  ])('`%s` ranks it first', async query => {
+    const {results} = (await search(query)).data;
+    expect(results[0], JSON.stringify(results.slice(0, 3))).toMatchObject({
+      domain: 'doc',
+      name: 'cli/commands/integration-check',
+    });
+  });
+});

package/api/search/search.mjs

@@ -57,9 +57,10 @@
  * Between domains, ranking adds one rule ahead of the score: domain priority
  * (see {@link domainPriority}). A component, hook, template, or theme whose
  * name or keyword a query word hits ranks ahead of every doc the reader did not
- * ask for by name or title, so `font size` finds `Text` before a typography
- * topic that declares the phrase. A doc the query names, or whose title the
- * query holds, keeps its place.
+ * ask for by name, title, or a declared phrase, so `font size` finds `Text`
+ * before a token page whose heading holds the phrase. A doc the query names,
+ * whose title the query holds, or that declares the whole query as a keyword
+ * keeps its place.
  *
  * Description and guidance are separate tiers on purpose. A component's own
  * one-line description saying "notification" is a claim about what it IS; the
@@ -92,7 +93,9 @@ import {
   familyMember,
   findComponentReadme,
   forEachIntegrationDoc,
+  integrationMemberEntry,
   integrationRecordHold,
+  isIntegrationMember,
   resolveImportPath,
   resolveIntegrationImportPath,
   CORE_PACKAGE,
@@ -136,6 +139,9 @@ import {setResultCoverage} from './coverage.mjs';
  * @property {string[]} [aliases] - Other names the candidate answers to, scored
  *   with the same name signals: a theme's display name.
  * @property {string[]} [keywords]
+ * @property {string[]} [_declared] - A doc's own declared keywords: what its
+ *   author lists in `keywords`, without the code terms and table cells its
+ *   other keywords add.
  * @property {string[]} [weakKeywords]
  * @property {string} [description]
  * @property {string[]} [prose]
@@ -511,19 +517,20 @@ const STRONG_TOKEN_SCORE = 70;
  *   typography/font-setup, `side panel` is "Side panels");
  * - 1: a word of the query is the topic's name (`illustration` in a longer
  *   question is the illustrations guide);
+ * - 1: a query of two or more words is one of the topic's own declared
+ *   keywords, whatever the plural (`code review` on a guide that declares it);
  * - 1: the query holds one of the doc's titles whole (`resizable side panels`
  *   names "Side panels"; `light dark mode button` names "Light/Dark Mode");
  * - 1: the doc matches every word of the query and one of them is a word of
  *   its title (`switch to a dark theme` and "Use a theme").
  * A section answers to its topic's name.
  *
- * A doc that matched only by keyword, by a heading holding the query, or by
+ * A doc that matched only by a heading holding the query, by one word, or by
  * words spread through its text has no priority. Docs are split into many
- * small topics, and each declares its own keywords and headings, so a common
- * phrase such as `font size` hits a guide's keyword or heading exactly
- * (170-190) while the component the reader is after matches one word by
- * keyword (`Text`, 98). Ranked on text alone, every split adds another doc
- * above the component. Broad reference pages match every word of many queries
+ * small topics, each with its own headings, so a common phrase such as
+ * `font size` hits a heading exactly (170) while the component the reader is
+ * after matches one word by keyword (`Text`, 98). Ranked on text alone, every
+ * split adds another doc above the component. Broad reference pages match every word of many queries
  * in their text the same way. The score stays the text-match strength the
  * result reports, so callers that gate on it (`build`) see the same numbers.
  *
@@ -549,6 +556,20 @@ export function domainPriority(term, tokens, candidate, hit) {
     if (named.some(n => samePhrase(term, n))) {
       return 2;
     }
+    // A query of two or more words that is one of the doc's own declared
+    // keywords, read as words whatever the plural, is the author naming the
+    // doc for that phrase: `code review` on a guide that declares it. Only
+    // what the author declared counts: the code terms and table cells a
+    // doc's other keywords add (`missing_field`) name what it mentions, not
+    // what it is for. One word is left out too, and a section declares
+    // nothing.
+    if (
+      phraseWords(term).length >= 2 &&
+      candidate._section == null &&
+      (candidate._declared ?? []).some(k => samePhrase(term, String(k)))
+    ) {
+      return 1;
+    }
     if (
       words.some(
         w =>
@@ -1144,24 +1165,31 @@ async function gatherIntegrationComponents(loadedIntegrations) {
     const renamed = new Set(
       discovered
         .filter(rec => integrationRecordHold(rec) === 'doc')
+        .filter(rec => !isIntegrationMember(rec))
         .map(rec => rec.docPath),
     );
     forEachIntegrationDoc(integration.components, (docPath, stem) => {
       if (!renamed.has(docPath)) hold(fileNamed, stem, docPath);
     });
     for (const rec of components) {
-      const doc = await loadModuleDoc(rec.docPath);
+      const loaded = await loadModuleDoc(rec.docPath);
+      // A family member is indexed from its own entry: the family's keywords
+      // and guidance describe the family.
+      const member = isIntegrationMember(rec);
+      const doc = member ? integrationMemberEntry(loaded, rec) : loaded;
       // A doc that names another export of its file still answers to the
       // file's name, as `component <file name>` does.
       const fileName = docStem(rec.docPath);
-      if (renamed.has(rec.docPath)) {
+      if (integrationRecordHold(rec) === 'doc') {
         hold(documented, rec.name, rec.docPath);
+      }
+      if (renamed.has(rec.docPath) && !member) {
         hold(documented, fileName, rec.docPath);
       }
       candidates.push({
         domain: 'component',
         name: rec.name,
-        aliases: fileName !== rec.name ? [fileName] : [],
+        aliases: !member && fileName !== rec.name ? [fileName] : [],
         _hold: integrationRecordHold(rec),
         _docPath: rec.docPath,
         keywords: doc && Array.isArray(doc.keywords) ? doc.keywords : [],
@@ -1183,7 +1211,7 @@ async function gatherIntegrationComponents(loadedIntegrations) {
             packageName: rec.package,
           },
           rec.name,
-          doc?.import,
+          loaded?.import,
         ),
       });
     }
@@ -1319,10 +1347,13 @@ export async function componentKeywords(coreDir, cwd) {
   const integrations = loadedIntegrations.map(async integration => {
     const {components} = await discoverValidIntegrationComponents(integration);
     return Promise.all(
-      components.map(async rec => ({
-        name: rec.name,
-        keywords: keywordsOf(await loadModuleDoc(rec.docPath)),
-      })),
+      components.map(async rec => {
+        const loaded = await loadModuleDoc(rec.docPath);
+        return {
+          name: rec.name,
+          keywords: keywordsOf(integrationMemberEntry(loaded, rec) ?? loaded),
+        };
+      }),
     );
   });
   return [
@@ -1496,6 +1527,10 @@ async function gatherDocs(cwd) {
         ...defined,
         ...codeTerms({content}),
       ],
+      _declared: [
+        ...(Array.isArray(selfDoc?.keywords) ? selfDoc.keywords : []),
+        ...(Array.isArray(node.keywords) ? node.keywords : []),
+      ],
       description: node.summary || '',
       prose: sectionProse({title: node.title, content}),
       titles: [node.title],
@@ -1632,6 +1667,7 @@ function topicCandidates(
         ...(doc?.title || title ? [doc?.title || title] : []),
         ...(Array.isArray(doc?.keywords) ? doc.keywords : []),
       ],
+      _declared: Array.isArray(doc?.keywords) ? doc.keywords : [],
       description: doc?.description || summary,
       prose: split
         ? sections.map(section => section.title).filter(Boolean)

package/api/theme/build/build.family.test.mjs

@@ -13,6 +13,7 @@ import {themeBuild, themeBuildFamily} from './build.mjs';
 import {interceptCore} from './core-interception.mjs';
 import {ensureCoreBuilt} from '../../../clients/cli/commands/ensure-core-built.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 vi.setConfig({testTimeout: 120_000});
 const CLI_ROOT = path.resolve(import.meta.dirname, '../../..');
 const FAMILY_KEY = 'ocean-family';
@@ -252,22 +253,69 @@ describe('themeBuildFamily()', () => {
     expect(fs.existsSync(dtsPath)).toBe(false);
   });
 
-  it('refuses family outputs outside cwd before checking or writing', async () => {
+  it('refuses to write family outputs outside cwd, and checks them read-only', async () => {
     const dir = makeDir();
     const files = writeFamily(dir).map(file => path.join(dir, file));
     const app = path.join(dir, 'app');
     fs.mkdirSync(app);
 
-    for (const check of [false, true]) {
-      await expect(
-        themeBuildFamily(files, {familyKey: FAMILY_KEY, check}, {cwd: app}),
-      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
-    }
+    await expect(
+      themeBuildFamily(files, {familyKey: FAMILY_KEY}, {cwd: app}),
+    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    const checked = await themeBuildFamily(
+      files,
+      {familyKey: FAMILY_KEY, check: true},
+      {cwd: app},
+    );
+    expect(checked?.type).toBe('theme.build.check');
+    expect(checked?.data.upToDate).toBe(false);
+    // The `.css.d.ts` import stub may be absent in check mode.
+    expect(checked?.data.stale).toEqual(
+      OUTPUTS.filter(file => !file.endsWith('.css.d.ts')).map(file => ({
+        path: `../themes/${file}`,
+        reason: 'missing',
+      })),
+    );
     for (const output of OUTPUTS) {
       expect(fs.existsSync(path.join(dir, 'themes', output))).toBe(false);
     }
   });
 
+  it('ends a stale family report for outputs outside cwd with a remedy that works', async () => {
+    const dir = makeDir();
+    const files = writeFamily(dir).map(file => path.join(dir, file));
+    const app = path.join(dir, 'app');
+    fs.mkdirSync(app);
+    const family = ['--family', ...files, '--family-key', FAMILY_KEY];
+
+    const stale = await runCli(['theme', 'build', ...family, '--check'], app);
+    expect(stale.code).toBe(1);
+    // The old remedy ran the build from cwd, which refuses these outputs.
+    expect(stale.stderr).not.toContain('Rebuild with:');
+
+    const lines = stale.stderr.split('\n').map(line => line.trim());
+    const runDir = lines.find(line => line.startsWith('cd '))?.slice(3);
+    expect(runDir).toBe(fs.realpathSync(path.join(dir, 'themes')));
+    const stem = `${getCliInvocation(runDir)} theme build `;
+    const [buildArgs, checkArgs] = lines
+      .filter(line => line.startsWith(stem))
+      .map(line => line.slice(stem.length).split(' '));
+    expect(checkArgs).toEqual([...buildArgs, '--check']);
+
+    // Following the remedy builds, and the check from there passes.
+    const built = await runCli(['theme', 'build', ...buildArgs], runDir);
+    expect(built.code).toBe(0);
+    for (const output of OUTPUTS) {
+      expect(fs.existsSync(path.join(dir, 'themes', output))).toBe(true);
+    }
+    const checked = await runCli(
+      ['--json', 'theme', 'build', ...checkArgs],
+      runDir,
+    );
+    expect(checked.code).toBe(0);
+    expect(JSON.parse(checked.stdout).data.upToDate).toBe(true);
+  });
+
   it('fails without publishing a mixed trio when staging a write fails', async () => {
     const dir = makeDir();
     const files = writeFamily(dir);

package/api/theme/build/build.mjs

@@ -27,8 +27,10 @@
  * files; an internal callback lets the CLI make only the process status fail.
  * Human progress is emitted through the shared `logger` (silent by default), so
  * the CLI keeps its exact output while a programmatic caller stays quiet.
- * Every output, explicit or beside the theme file, stays inside `cwd`
- * (`ERR_PATH_TRAVERSAL` otherwise), in check mode too.
+ * Every output a build writes, explicit or beside the theme file, stays inside
+ * `cwd` (`ERR_PATH_TRAVERSAL` otherwise). Check mode writes nothing, so it
+ * compares outputs outside `cwd` read-only; only a relative `out` path that
+ * escapes `cwd` is refused there too.
  *
  * The installed `@astryxdesign/core` is an independently versioned optional
  * peer, so it can be older than the CLI. A theme that uses only baseline
@@ -60,7 +62,10 @@ import {isBuiltin} from 'node:module';
 import {fileURLToPath, pathToFileURL} from 'node:url';
 import {parse} from '@babel/parser';
 import {createJiti} from 'jiti';
-import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {
+  formatCliCommand,
+  getCliInvocation,
+} from '../../../foundation/env/package-manager.mjs';
 import {
   CLI_ROOT,
   findCoreDir,
@@ -568,6 +573,86 @@ function confineOutputs(writes, root, remedy) {
   for (const write of writes) confineOutput(write.dest, root, remedy);
 }
 
+/** @param {string} dest absolute output path @param {string} root @returns {boolean} whether a build at `root` refuses to write `dest` */
+function refusedOutput(dest, root) {
+  try {
+    confineOutput(dest, root, '');
+    return false;
+  } catch (err) {
+    if (
+      err instanceof AstryxError &&
+      err.code === ERROR_CODES.ERR_PATH_TRAVERSAL
+    )
+      return true;
+    throw err;
+  }
+}
+
+/** @param {string[]} dirs absolute directories @returns {string | null} the deepest directory containing all of them, or null across roots */
+function commonDirectory(dirs) {
+  let common = dirs[0];
+  for (const dir of dirs.slice(1)) {
+    while (
+      path.relative(common, dir).startsWith('..') ||
+      path.isAbsolute(path.relative(common, dir))
+    ) {
+      const parent = path.dirname(common);
+      if (parent === common) return null;
+      common = parent;
+    }
+  }
+  return common;
+}
+
+/** @param {string} value @returns {string} `value` as one shell word */
+function shellWord(value) {
+  if (/^[A-Za-z0-9@%+=:,./_-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * How a stale check report ends when outputs sit outside the write root. A
+ * build there refuses them, and each output's `Source:` header records the
+ * directory its build ran from, so the build and the check both run from the
+ * nearest directory that contains every theme file and output.
+ * @param {Array<{dest: string}>} writes
+ * @param {string[]} sources absolute theme files the build reads
+ * @param {string} root the directory a build here keeps its writes inside
+ * @param {(relative: (file: string) => string) => string[]} args the arguments after `theme build`, given each path relative to the directory to run from
+ * @returns {string[] | null} report lines, or null when every output is inside `root`
+ */
+function outsideCheckRemedy(writes, sources, root, args) {
+  if (!writes.some(write => refusedOutput(write.dest, root))) return null;
+  const real = (/** @type {string} */ file) => realLocation(path.resolve(file));
+  const dir = commonDirectory([
+    ...sources.map(file => path.dirname(real(file))),
+    ...writes.map(write => path.dirname(real(write.dest))),
+  ]);
+  if (!dir) {
+    return [
+      'These outputs are outside the working directory, so a build here refuses them. Build and check them from one directory that contains the theme files and the outputs.',
+    ];
+  }
+  const command = (/** @type {string[]} */ extra) =>
+    formatCliCommand(
+      [
+        'theme',
+        'build',
+        ...args(file => path.relative(dir, real(file))),
+        ...extra,
+      ]
+        .map(shellWord)
+        .join(' '),
+      dir,
+    );
+  return [
+    'These outputs are outside the working directory, so a build here refuses them, and each output records the directory it was built from. Build and check them from a directory that contains them:',
+    `  cd ${shellWord(dir)}`,
+    `  ${command([])}`,
+    `  ${command(['--check'])}`,
+  ];
+}
+
 /** @param {Array<{dest: string, content: string}>} writes */
 function writeBuildOutputs(writes) {
   if (writes.length === 0) return;
@@ -2859,9 +2944,13 @@ async function themeBuildInternal(
   const writeRoot = options.__writeRoot ?? cwd;
   let outPath;
   if (options.out) {
-    // Relative or absolute, the explicit output stays inside the write root.
     outPath = path.resolve(cwd, options.out);
-    confineOutput(outPath, writeRoot, OUT_REMEDY, options.out);
+    // A build keeps the explicit output inside the write root, relative or
+    // absolute. Check mode writes nothing, so it refuses only a relative path
+    // that escapes cwd.
+    if (!options.check || !path.isAbsolute(options.out)) {
+      confineOutput(outPath, writeRoot, OUT_REMEDY, options.out);
+    }
   } else {
     outPath = path.join(path.dirname(filePath), `${baseName}.css`);
   }
@@ -2957,10 +3046,12 @@ async function themeBuildInternal(
     writes.push({dest: variantDtsPath, content: variantContent});
   }
 
-  // Every output stays inside cwd, including the defaults beside the theme
-  // file. Check mode refuses the same paths, so it never passes outputs that a
-  // build would refuse to write.
-  confineOutputs(writes, writeRoot, options.out ? OUT_REMEDY : SOURCE_REMEDY);
+  // Every output a build writes stays inside cwd, including the defaults
+  // beside the theme file. Check mode writes nothing, so it compares outputs
+  // outside cwd read-only.
+  if (!options.check) {
+    confineOutputs(writes, writeRoot, options.out ? OUT_REMEDY : SOURCE_REMEDY);
+  }
 
   // Check mode: compare generated content against what's on disk instead of
   // writing. A file is "stale" if it's missing or its content differs once the
@@ -2980,7 +3071,10 @@ async function themeBuildInternal(
           `  ${s.reason === 'missing' ? 'missing' : 'stale'}: ${s.path}`,
         );
       }
-      logger.error(`\n  Rebuild with: ${buildCommand}`);
+      // prettier-ignore
+      const remedy = outsideCheckRemedy(writes, [filePath], writeRoot, relative => [relative(filePath), ...(options.out ? ['--out', relative(outPath)] : []), ...(options.iconsSpecifier ? ['--icons-specifier', options.iconsSpecifier] : [])]);
+      if (remedy) logger.error(`\n  ${remedy.join('\n  ')}`);
+      else logger.error(`\n  Rebuild with: ${buildCommand}`);
     }
     return {
       type: 'theme.build.check',
@@ -3093,7 +3187,7 @@ function printBuildTrailer(trailer) {
   logger.log(`
 Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${trailer.exportName} } from '${trailer.jsImport}';
   import '${trailer.cssImport}';
 
@@ -3103,7 +3197,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours lives
 
 Or with a <link> tag:
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${trailer.exportName} } from '${trailer.jsImport}';
 
   <link rel="stylesheet" href="${trailer.cssImport}" />
@@ -3129,7 +3223,7 @@ export function printBatchTrailer(trailers) {
   logger.log(`
 Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${first.exportName} } from '${first.jsImport}';
   import '${first.cssImport}';
 
@@ -3139,7 +3233,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours lives
 
 Or with a <link> tag:
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${first.exportName} } from '${first.jsImport}';
 
   <link rel="stylesheet" href="${first.cssImport}" />
@@ -3506,8 +3600,8 @@ export async function themeBuildFamily(
     js: path.relative(cwd, jsPath),
     dts: path.relative(cwd, dtsPath),
   };
-  // The family's outputs stay inside cwd too, in check mode as well.
-  confineOutputs(writes, cwd, FAMILY_REMEDY);
+  // A family build's outputs stay inside cwd too; check mode only reads them.
+  if (!options.check) confineOutputs(writes, cwd, FAMILY_REMEDY);
   if (options.check) {
     const stale = staleBuildOutputs(writes, cwd);
     const upToDate = stale.length === 0;
@@ -3524,7 +3618,10 @@ export async function themeBuildFamily(
           `  ${entry.reason === 'missing' ? 'missing' : 'stale'}: ${entry.path}`,
         );
       }
-      logger.error(`\n  Rebuild with: ${buildCommand}`);
+      // prettier-ignore
+      const remedy = outsideCheckRemedy(writes, members.map(member => member.filePath), cwd, relative => ['--family', ...members.map(member => relative(member.filePath)), '--family-key', baseName, ...(options.iconsSpecifier ? ['--icons-specifier', options.iconsSpecifier] : [])]);
+      if (remedy) logger.error(`\n  ${remedy.join('\n  ')}`);
+      else logger.error(`\n  Rebuild with: ${buildCommand}`);
     }
     return {
       type: 'theme.build.check',