@astryxdesign/cli 0.7.12 → 0.7.13-canary.a5ad1f2

package/api/doctor/_adapter.d.mts

@@ -20,6 +20,21 @@ export function readTextFileIfExists(file: string): string | null;
 export function listProjectSourceFiles(root: string, generatedModule: string, options?: {
     stylesheets?: boolean;
 }): string[];
+/**
+ * Each file in the project's own source that still uses the placeholder
+ * component the CLI writes for a missing icon: the file, the component's
+ * name, the meanings its uses name (null when none names one), and how many
+ * uses it has. A file reads only as a syntax tree, so a commented-out or
+ * quoted copy never counts. Read without executing app code.
+ * @param {string} projectDir
+ * @returns {Array<{file: string, local: string, meanings: string[] | null, uses: number}>}
+ */
+export function findIconPlaceholders(projectDir: string): Array<{
+    file: string;
+    local: string;
+    meanings: string[] | null;
+    uses: number;
+}>;
 /** @param {string} projectDir */
 export function discoverDoctorThemes(projectDir: string): Promise<import("../../foundation/discovery/theme-discovery.mjs").DiscoveredTheme[]>;
 /**
@@ -231,6 +246,8 @@ export function readBuiltPath(target: string, { fileLimit }?: {
  * @returns {string[]}
  */
 export function builtIntegrationPackages(target: string, cwd: string): string[];
+export { placeholderFixes } from "../../foundation/discovery/template-icons.mjs";
+export { unlistedIconSets } from "../../foundation/discovery/icon-set-discovery.mjs";
 export { resolveRecordedTheme } from "../theme/theme.mjs";
 export { collectUnloadedFonts } from "../theme/build/font-warning.mjs";
 export const SOURCE_EXTENSIONS: Set<string>;

package/api/doctor/_adapter.mjs

@@ -39,6 +39,9 @@ import {
 } from '../../foundation/agent-docs/computer-agent-text.mjs';
 import {computerAgentTextSettings} from '../../foundation/env/user-settings.mjs';
 import * as fs from 'node:fs';
+import {placeholderUses} from '../../foundation/discovery/template-icons.mjs';
+export {placeholderFixes} from '../../foundation/discovery/template-icons.mjs';
+export {unlistedIconSets} from '../../foundation/discovery/icon-set-discovery.mjs';
 import {elementPropOrigins} from '../../foundation/discovery/module-exports.mjs';
 import {cssImports} from '../../foundation/render/embedded-imports.mjs';
 import * as path from 'node:path';
@@ -150,6 +153,43 @@ export function listProjectSourceFiles(root, generatedModule, options = {}) {
   return files;
 }
 
+/**
+ * Each file in the project's own source that still uses the placeholder
+ * component the CLI writes for a missing icon: the file, the component's
+ * name, the meanings its uses name (null when none names one), and how many
+ * uses it has. A file reads only as a syntax tree, so a commented-out or
+ * quoted copy never counts. Read without executing app code.
+ * @param {string} projectDir
+ * @returns {Array<{file: string, local: string, meanings: string[] | null, uses: number}>}
+ */
+export function findIconPlaceholders(projectDir) {
+  /** @type {Array<{file: string, local: string, meanings: string[] | null, uses: number}>} */
+  const found = [];
+  for (const file of listProjectSourceFiles(projectDir, '')) {
+    let source;
+    try {
+      source = readTextFile(file);
+    } catch {
+      continue;
+    }
+    // Only a file with the placeholder's dash pattern is parsed.
+    if (!source.includes('3 2.33')) continue;
+    const uses = placeholderUses(source);
+    if (!uses || uses.length === 0) continue;
+    const shown = path.relative(projectDir, file).split(path.sep).join('/');
+    const meanings = [
+      ...new Set(uses.flatMap(each => each.meanings ?? [])),
+    ].sort();
+    found.push({
+      file: shown,
+      local: uses[0].local,
+      meanings: meanings.length > 0 ? meanings : null,
+      uses: uses.length,
+    });
+  }
+  return found.sort((a, b) => a.file.localeCompare(b.file));
+}
+
 /** @param {string} projectDir */
 export async function discoverDoctorThemes(projectDir) {
   const project = await Project.load(projectDir, {core: 'project'});

package/api/doctor/doctor.d.mts

@@ -87,16 +87,25 @@ export function checkPeerDeps(ctx: DoctorContext): DoctorCheck;
  */
 export function checkIntegrationIssues(ctx: DoctorContext): DoctorCheck;
 /**
- * The project's icon sets (AST-084 FR17). Fails when `experimental.iconSet` names a set
- * that is not installed, or one that is installed but withdrawn (with why);
- * warns when two or more sets are installed and none is the project's, and
- * for each other installed set that was withdrawn, with why.
+ * The project's icon sets (AST-084 FR17). Fails when `experimental.iconSet`
+ * names a set, main or backup, that is not installed, that is installed but
+ * withdrawn (with why), or that two packages ship under one name; and when
+ * more than one set is installed and the list leaves one out. Warns for each
+ * other installed set that was withdrawn, with why.
  * Icon sets are experimental (spec:AST-017 FR27): only a project that sets
  * `experimental.iconSet` gets the check, so every other report is unchanged.
  * @param {DoctorContext} ctx
  * @returns {DoctorCheck | null}
  */
 export function checkIconSets(ctx: DoctorContext): DoctorCheck | null;
+/**
+ * The placeholder component for a missing icon, still in the project's own
+ * source (AST-084): each file and the meanings it stands for, with the commands that give each a
+ * real icon. Only a project that sets `experimental.iconSet` gets the check.
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck | null}
+ */
+export function checkIconPlaceholders(ctx: DoctorContext): DoctorCheck | null;
 /**
  * Check 10 — report the detected package manager, and say so when the project's
  * own declaration disagrees with what is on disk.
@@ -448,8 +457,29 @@ export type DoctorContext = {
             status: "selected" | "none" | "ambiguous" | "missing" | "withdrawn";
             reason: string;
             configured?: string;
+            backups?: Array<{
+                selector: string;
+                status: "selected" | "ambiguous" | "missing" | "withdrawn";
+                reason: string;
+            }>;
+            order?: Array<{
+                name: string;
+                package: string;
+            }>;
         };
     } | null | undefined;
+    /**
+     * Each file in the project's own source that uses the placeholder component
+     * the CLI writes for a missing icon, read only in a project that sets
+     * `experimental.iconSet`; null otherwise.
+     * Experimental: may change or be removed in a patch release.
+     */
+    iconPlaceholders?: {
+        file: string;
+        local: string;
+        meanings: string[] | null;
+        uses: number;
+    }[] | null | undefined;
     /**
      * - Why the CLI could not load the
      * project from its config, when it could not. Checks that need the loaded

package/api/doctor/doctor.mjs

@@ -42,6 +42,7 @@ import {
 } from '../../foundation/agent-docs/agent-docs.mjs';
 import {
   CLI_ROOT,
+  findPackageRoot,
   findProjectCoreDir,
   findInstalledPackage,
 } from '../../foundation/fs/paths.mjs';
@@ -107,6 +108,9 @@ import {
   projectCoreVersion,
   projectHasOwnCli,
   computerIntegrationsOutside,
+  findIconPlaceholders,
+  placeholderFixes,
+  unlistedIconSets,
   computerIntegrationsToAdd,
   displayHomePath,
   outsideProject,
@@ -157,9 +161,14 @@ import {checkBuilt} from './built-checks.mjs';
  *   Combined project-level integration issues, including cross-package template replacement warnings.
  * @property {Error|null} [configError] - Error thrown while resolving the config
  *   path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
- * @property {{sets: Array<{name: string, package: string}>, withdrawn: Array<{name: string, package: string, reason: string}>, choice: {status: 'selected'|'none'|'ambiguous'|'missing'|'withdrawn', reason: string, configured?: string}}|null} [iconSets]
+ * @property {{sets: Array<{name: string, package: string}>, withdrawn: Array<{name: string, package: string, reason: string}>, choice: {status: 'selected'|'none'|'ambiguous'|'missing'|'withdrawn', reason: string, configured?: string, backups?: Array<{selector: string, status: 'selected'|'ambiguous'|'missing'|'withdrawn', reason: string}>, order?: Array<{name: string, package: string}>}}|null} [iconSets]
  *   The project's icon sets (AST-084 FR17), or null when they could not be read.
  *   Experimental: may change or be removed in a patch release.
+ * @property {Array<{file: string, local: string, meanings: string[] | null, uses: number}>|null} [iconPlaceholders]
+ *   Each file in the project's own source that uses the placeholder component
+ *   the CLI writes for a missing icon, read only in a project that sets
+ *   `experimental.iconSet`; null otherwise.
+ *   Experimental: may change or be removed in a patch release.
  * @property {string|null} [projectError] - Why the CLI could not load the
  *   project from its config, when it could not. Checks that need the loaded
  *   project quote it when they skip, so a skip says what was found.
@@ -996,10 +1005,11 @@ export function checkIntegrationIssues(ctx) {
 }
 
 /**
- * The project's icon sets (AST-084 FR17). Fails when `experimental.iconSet` names a set
- * that is not installed, or one that is installed but withdrawn (with why);
- * warns when two or more sets are installed and none is the project's, and
- * for each other installed set that was withdrawn, with why.
+ * The project's icon sets (AST-084 FR17). Fails when `experimental.iconSet`
+ * names a set, main or backup, that is not installed, that is installed but
+ * withdrawn (with why), or that two packages ship under one name; and when
+ * more than one set is installed and the list leaves one out. Warns for each
+ * other installed set that was withdrawn, with why.
  * Icon sets are experimental (spec:AST-017 FR27): only a project that sets
  * `experimental.iconSet` gets the check, so every other report is unchanged.
  * @param {DoctorContext} ctx
@@ -1013,38 +1023,66 @@ export function checkIconSets(ctx) {
   const {sets, withdrawn, choice} = state;
   // Only a project that opts in with `experimental.iconSet` gets the check.
   if (!choice.configured) return null;
-  if (choice.status === 'missing') {
+  const list = [
+    {selector: choice.configured, status: choice.status, reason: choice.reason},
+    ...(choice.backups ?? []),
+  ];
+  const installFix =
+    'Install the package that ships the set, or remove it from experimental.iconSet in astryx.config (`astryx experimental icon --list` names the installed sets).';
+  const missing = list.filter(each => each.status === 'missing');
+  if (missing.length > 0) {
     return {
       id,
       label,
       status: 'fail',
-      message: choice.reason,
-      fix: 'Install the package that ships the set, or set experimental.iconSet in astryx.config to an installed set (`astryx experimental icon --list` names them).',
+      message: missing.map(each => each.reason).join(' | '),
+      fix: installFix,
     };
   }
-  if (choice.status === 'withdrawn') {
+  const gone = list.filter(each => each.status === 'withdrawn');
+  if (gone.length > 0) {
     return {
       id,
       label,
       status: 'fail',
-      message: choice.reason,
-      fix: 'Run `astryx integration check` in the package that ships the set, or install the module its data names; or set experimental.iconSet in astryx.config to a valid installed set (`astryx experimental icon --list` names them).',
+      message: gone.map(each => each.reason).join(' | '),
+      fix: 'Run `astryx integration check` in the package that ships the set, or install the module its data names; or remove it from experimental.iconSet in astryx.config (`astryx experimental icon --list` names the valid installed sets).',
     };
   }
-  /** @type {string[]} */
-  const problems = [];
-  if (choice.status === 'ambiguous') problems.push(choice.reason);
-  for (const each of withdrawn) problems.push(each.reason);
-  if (problems.length > 0) {
+  const shared = list.filter(each => each.status === 'ambiguous');
+  if (shared.length > 0) {
+    return {
+      id,
+      label,
+      status: 'fail',
+      message: shared.map(each => each.reason).join(' | '),
+      fix: 'Write each name in experimental.iconSet as "<package>/<set>" (`astryx experimental icon --list` names them).',
+    };
+  }
+  const order = choice.order ?? [];
+  const unlisted = sets.filter(set => !order.includes(set));
+  if (sets.length > 1 && unlisted.length > 0) {
+    const {problem, fix} = unlistedIconSets(
+      sets.length,
+      list[0].selector,
+      list.slice(1).map(each => each.selector),
+      unlisted.map(set => `${set.package}/${set.name}`),
+    );
+    return {
+      id,
+      label,
+      status: 'fail',
+      message: `${problem} (experimental.iconSet), so which set a copied template uses is not decided.`,
+      fix,
+    };
+  }
+  if (withdrawn.length > 0) {
     return {
       id,
       label,
       status: 'warn',
-      message: problems.join(' | '),
-      fix:
-        choice.status === 'ambiguous'
-          ? 'Set experimental.iconSet in astryx.config to "<package>/<set>" so templates use one set.'
-          : 'Run `astryx integration check` in the package that ships the set, or install its module.',
+      message: withdrawn.map(each => each.reason).join(' | '),
+      fix: 'Run `astryx integration check` in the package that ships the set, or install its module.',
     };
   }
   return {
@@ -1055,6 +1093,48 @@ export function checkIconSets(ctx) {
   };
 }
 
+/**
+ * The placeholder component for a missing icon, still in the project's own
+ * source (AST-084): each file and the meanings it stands for, with the commands that give each a
+ * real icon. Only a project that sets `experimental.iconSet` gets the check.
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck | null}
+ */
+export function checkIconPlaceholders(ctx) {
+  const choice = ctx.iconSets?.choice;
+  if (!choice?.configured || ctx.iconPlaceholders == null) return null;
+  const id = 'icon-placeholders';
+  const label = 'Placeholder icons';
+  const found = ctx.iconPlaceholders;
+  if (found.length === 0) {
+    return {
+      id,
+      label,
+      status: 'pass',
+      message: 'No copied code uses the placeholder for a missing icon.',
+    };
+  }
+  const main = choice.configured;
+  const meanings = [
+    ...new Set(found.flatMap(each => each.meanings ?? [])),
+  ].sort();
+  const where = found
+    .map(
+      each =>
+        `${each.file} (${each.meanings ? each.meanings.join(', ') : 'meaning not recorded'})`,
+    )
+    .join(', ');
+  const uses = found.reduce((total, each) => total + each.uses, 0);
+  const [mapFix, backupFix] = placeholderFixes(meanings, main);
+  return {
+    id,
+    label,
+    status: 'warn',
+    message: `${uses} placeholder icon${uses === 1 ? '' : 's'} in copied code: no set in your list has ${meanings.length > 0 ? `"${meanings.join('", "')}"` : 'these icons'}. ${where}.`,
+    fix: `Add a backup set that has each meaning (\`astryx discover --type icon-set\` lists sets and the definitions they map): \`${backupFix}\`; or, if you author your main set, map it there: \`${mapFix}\`. Then copy the template again, or replace each use of the placeholder (\`${found[0].local}\`) with the icon \`astryx experimental icon <meaning>\` prints, and delete its declaration. A built-in meaning (\`astryx experimental icon --definitions\` marks them) also renders from the theme by name: \`<Icon icon="<name>" />\`. Otherwise, use your own icon component (\`astryx docs icons custom-icons\`).`,
+  };
+}
+
 /**
  * Check 10 — report the detected package manager, and say so when the project's
  * own declaration disagrees with what is on disk.
@@ -2151,6 +2231,7 @@ export const SYNC_CHECKS = [
   checkProviderIdentity,
   checkIntegrationIssues,
   checkIconSets,
+  checkIconPlaceholders,
   checkAgentDocs,
   checkPeerDeps,
   checkPackageManager,
@@ -2218,6 +2299,8 @@ export async function runChecks(options = {}) {
   let projectError = null;
   /** @type {DoctorContext['iconSets']} */
   let iconSets = null;
+  /** @type {DoctorContext['iconPlaceholders']} */
+  let iconPlaceholders = null;
   /** @type {import('../../foundation/config/project.mjs').Project | null} */
   let project = null;
   try {
@@ -2315,6 +2398,9 @@ export async function runChecks(options = {}) {
       }
       try {
         iconSets = await project.iconSets();
+        if (iconSets.choice.configured) {
+          iconPlaceholders = findIconPlaceholders(findPackageRoot(cwd) ?? cwd);
+        }
       } catch {
         iconSets = null;
       }
@@ -2344,6 +2430,7 @@ export async function runChecks(options = {}) {
     configError,
     projectError,
     iconSets,
+    iconPlaceholders,
   };
 
   /** @type {DoctorCheck[]} */

package/api/icon/_adapter.d.mts

@@ -43,14 +43,17 @@ export function loadIconProject(cwd: string): Promise<{
  * `experimental.iconSet`, read from the project's package.json; null when
  * nothing says so.
  * @param {string} projectDir
+ * @param {{list?: boolean}} [options] `list`: the value written is a list
  * @returns {string | null}
  */
-export function iconSetConfigCliWarning(projectDir: string): string | null;
+export function iconSetConfigCliWarning(projectDir: string, options?: {
+    list?: boolean;
+}): string | null;
 export { astryxIconDefinitions } from "../../foundation/discovery/icon-definition-discovery.mjs";
-export { iconSetKey } from "../../foundation/discovery/icon-set-discovery.mjs";
-export { setConfigString } from "../../foundation/config/config-writer.mjs";
 export { exportValueKind } from "../../foundation/discovery/module-exports.mjs";
 export { iconRecord, importLine, leadingReading, matchIcon, answeringMatches, rankIcons, scoreIcon } from "../../foundation/discovery/icon-ranking.mjs";
+export { iconSetKey, ICON_USE_ORDER_COMMAND, unlistedIconSets } from "../../foundation/discovery/icon-set-discovery.mjs";
+export { setConfigString, setConfigValue } from "../../foundation/config/config-writer.mjs";
 export { assertIconExport, checkNewDefinition, definitionNameFromInput, definitionFile, findLocalIconSet, writeDefinitionFile, iconIdOf, closestNames, libraryIcons, mappableDefinitions, resolveIconSource, generatedModulePath, generatedNamesOf, generatedOrigins, iconModulePackage, sameIconModule, iconExportName, iconNaming, modulePrefix, moduleNaming, iconNamingWithoutLook, splitLook, setModuleNote, variantExportName, writeGeneratedIcons, writeIconSetData, definitionNameOf, iconIdIn, iconsWithWord, localSourceNote, THEME_MAP_NAME } from "../../foundation/discovery/icon-set-writer.mjs";
 export { addIconDefinition, addIconSet } from "./_authoring.mjs";
 export { checkVariantLook, drawnLooks } from "./_default-look.mjs";

package/api/icon/_adapter.mjs

@@ -34,7 +34,14 @@ export {
 } from '../../foundation/discovery/icon-ranking.mjs';
 export {astryxIconDefinitions} from '../../foundation/discovery/icon-definition-discovery.mjs';
 export {iconSetKey} from '../../foundation/discovery/icon-set-discovery.mjs';
-export {setConfigString} from '../../foundation/config/config-writer.mjs';
+export {
+  setConfigString,
+  setConfigValue,
+} from '../../foundation/config/config-writer.mjs';
+export {
+  ICON_USE_ORDER_COMMAND,
+  unlistedIconSets,
+} from '../../foundation/discovery/icon-set-discovery.mjs';
 export {
   assertIconExport,
   checkNewDefinition,
@@ -177,9 +184,10 @@ function findProjectDir(cwd) {
  * `experimental.iconSet`, read from the project's package.json; null when
  * nothing says so.
  * @param {string} projectDir
+ * @param {{list?: boolean}} [options] `list`: the value written is a list
  * @returns {string | null}
  */
-export function iconSetConfigCliWarning(projectDir) {
+export function iconSetConfigCliWarning(projectDir, options = {}) {
   let pkg;
   try {
     pkg = JSON.parse(
@@ -188,5 +196,5 @@ export function iconSetConfigCliWarning(projectDir) {
   } catch {
     return null;
   }
-  return projectIconSetCliWarning(pkg);
+  return projectIconSetCliWarning(pkg, options);
 }

package/api/icon/icon.type.d.mts

@@ -128,6 +128,14 @@ export type IconSetEntry = {
      * - Whether this is the project's icon set.
      */
     project: boolean;
+    /**
+     * - The set's place in the project's list: its main set, a backup, or not listed.
+     */
+    role: "main" | "backup" | null;
+    /**
+     * - The set's position in the list, the main set at 1; null when it is not listed.
+     */
+    rank: number | null;
 };
 /**
  * Which icon definitions one set's `map` covers.
@@ -170,6 +178,13 @@ export type IconListResponse = {
         status: "selected" | "none" | "ambiguous" | "missing" | "withdrawn";
         projectSet: string | null;
         reason: string;
+        order: string[];
+        backups: Array<{
+            iconSet: string;
+            status: "selected" | "ambiguous" | "missing" | "withdrawn";
+            reason: string;
+        }>;
+        next?: string | undefined;
         sets: IconSetEntry[];
         withdrawn: IconWithdrawnEntry[];
     };
@@ -182,10 +197,16 @@ export type IconUseResponse = {
     data: {
         iconSet: string;
         set: string;
+        backups: Array<{
+            iconSet: string;
+            set: string;
+        }>;
         config: string;
         created: boolean;
-        previous: string | null;
+        previous: string | string[] | null;
         changed: boolean;
+        unlisted: string[];
+        next?: string | undefined;
         warning?: string | undefined;
     };
 };

package/api/icon/icon.type.mjs

@@ -84,6 +84,8 @@
  * @property {string[] | null} variants - The variants the set declares: named looks such as outline or solid; size comes from CSS.
  * @property {IconSetCoverage} coverage - Which icon definitions the set's `map` covers.
  * @property {boolean} project - Whether this is the project's icon set.
+ * @property {'main' | 'backup' | null} role - The set's place in the project's list: its main set, a backup, or not listed.
+ * @property {number | null} rank - The set's position in the list, the main set at 1; null when it is not listed.
  */
 
 /**
@@ -113,7 +115,10 @@
  * @property {'selected' | 'none' | 'ambiguous' | 'missing' | 'withdrawn'} data.status - The project's icon-set state.
  * @property {string | null} data.projectSet - The project's set, as `<package>/<set>`, when selected.
  * @property {string} data.reason - Why the project has that set, or none.
- * @property {IconSetEntry[]} data.sets - Installed sets, the project's first.
+ * @property {string[]} data.order - The project's list as `<package>/<set>`: the main set, then each backup that resolves; empty when no main set is selected.
+ * @property {Array<{iconSet: string, status: 'selected' | 'ambiguous' | 'missing' | 'withdrawn', reason: string}>} data.backups - Each backup the list names, and whether it resolves.
+ * @property {string} [data.next] - Present when two or more sets are installed and none is the main set: the command that chooses the order.
+ * @property {IconSetEntry[]} data.sets - Installed sets in list order: the main set, its backups, then the rest.
  * @property {IconWithdrawnEntry[]} data.withdrawn - Sets found but withdrawn.
  */
 
@@ -123,12 +128,15 @@
  * @typedef {object} IconUseResponse
  * @property {'icon.use'} type
  * @property {object} data
- * @property {string} data.iconSet - The value written to `experimental.iconSet`.
- * @property {string} data.set - The set it names, as `<package>/<set>`.
+ * @property {string} data.iconSet - The main set, as written to `experimental.iconSet` (alone, or first in the list).
+ * @property {string} data.set - The main set it names, as `<package>/<set>`.
+ * @property {Array<{iconSet: string, set: string}>} data.backups - The backup sets, in order, as written and as `<package>/<set>`; empty when there are none.
  * @property {string} data.config - The config file, relative to the project.
  * @property {boolean} data.created - Whether the config file was created.
- * @property {string | null} data.previous - The `experimental.iconSet` value it replaced.
+ * @property {string | string[] | null} data.previous - The `experimental.iconSet` value it replaced.
  * @property {boolean} data.changed - Whether anything was written.
+ * @property {string[]} data.unlisted - Installed sets the list leaves out, as `<package>/<set>`. Doctor fails a project that installs more than one set and leaves one out.
+ * @property {string} [data.next] - Present when `unlisted` is not empty: the command that adds them as backups.
  * @property {string} [data.warning] - Present when the project's
  *   `@astryxdesign/cli` range admits a release before 0.7.4, which refuses
  *   an astryx.config that sets `experimental.iconSet`: what fails, and the

package/api/icon/iconUse.doc.mjs

@@ -10,13 +10,21 @@ export const doc = {
   namespace: 'cli/api',
   stability: 'experimental',
   displayName: 'iconUse()',
-  summary: "Choose the project's icon set.",
+  summary: "Choose the project's main icon set and backups.",
   description:
-    "Writes `experimental.iconSet` in the project's astryx.config (creating astryx.config.mjs when there is none), so templates and blocks the project copies use that set's icons. The set must be installed; a name two installed packages both ship is refused with each `<package>/<set>` form. Experimental: it may change or be removed in a patch release.",
+    "Writes `experimental.iconSet` in the project's astryx.config (creating astryx.config.mjs when there is none), so templates and blocks the project copies use that set's icons. With no backups it writes the set name as a string. With backups it writes a list, the main set first and then each backup in order: a copied template takes each icon from the first set in the list that has its meaning, and draws a placeholder the copied file declares when none has it. Every set must be installed; a name two installed packages both ship is refused with each `<package>/<set>` form. The receipt lists installed sets the list leaves out (`unlisted`), which Doctor fails, with the command that adds them. Experimental: it may change or be removed in a patch release.",
   importPath: '@astryxdesign/cli/api',
   signature:
-    'iconUse(set: string, options?: {cwd?: string}): Promise<IconUseResponse>',
-  keywords: ['icon', 'icon set', 'use', 'experimental.iconSet', 'config'],
+    'iconUse(set: string, options?: {cwd?: string, backups?: string[]}): Promise<IconUseResponse>',
+  keywords: [
+    'icon',
+    'icon set',
+    'use',
+    'backup',
+    'main set',
+    'experimental.iconSet',
+    'config',
+  ],
   params: [
     {
       name: 'set',
@@ -29,12 +37,18 @@ export const doc = {
       type: 'string',
       description: 'The project directory.',
     },
+    {
+      name: 'options.backups',
+      type: 'string[]',
+      description:
+        'Backup sets, by name or `<package>/<set>`, in the order a copied template tries them after the main set.',
+    },
   ],
   returns: [
     {
       type: 'icon.use',
       description:
-        "The value written, the set it names, the config file, whether it was created, the value it replaced, and a `warning` when the project's @astryxdesign/cli range admits a release before 0.7.4, which refuses the key.",
+        "The main set and the backups written, the sets they name, the config file, whether it was created, the value it replaced, the installed sets the list leaves out (`unlisted`, with a `next` command), and a `warning` when the project's @astryxdesign/cli range admits a release that refuses the value: before 0.7.4 for a string, before 0.7.12 for a list.",
     },
   ],
   throws: [
@@ -44,7 +58,7 @@ export const doc = {
     },
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: 'two installed packages ship a set with the name',
+      when: 'two installed packages ship a set with the name, or the list names one set twice',
     },
     {
       code: 'ERR_WRITE_FAILED',
@@ -67,7 +81,13 @@ export const doc = {
       when: 'the set name is missing',
     },
   ],
-  examples: [{label: 'Use a set', code: "await iconUse('outline');"}],
+  examples: [
+    {label: 'Use a set', code: "await iconUse('outline');"},
+    {
+      label: 'Use a main set with a backup',
+      code: "await iconUse('outline', {backups: ['@acme/brand-icons/brand']});",
+    },
+  ],
   command: 'experimental icon use',
   related: ['icon', 'iconMap', 'iconAdd'],
 };

package/api/icon/list/list.mjs

@@ -2,14 +2,19 @@
 
 /**
  * @file `icon.list` leaf (AST-084 FR7): every installed icon set with the
- * icon definitions its `map` covers, the project's set, and the sets
- * withdrawn with why.
+ * icon definitions its `map` covers, the project's main set and backups in
+ * order, and the sets withdrawn with why.
  *
  * @output the `icon.list` envelope
  * @position api/icon/list — dispatched by ../icon.mjs
  */
 
-import {astryxIconDefinitions, loadIconSets} from '../_adapter.mjs';
+import {
+  astryxIconDefinitions,
+  ICON_USE_ORDER_COMMAND,
+  iconSetKey,
+  loadIconSets,
+} from '../_adapter.mjs';
 
 /**
  * List the installed icon sets.
@@ -20,6 +25,8 @@ export async function iconList({cwd}) {
   const {sets, withdrawn, choice} = await loadIconSets(cwd);
   const astryx = astryxIconDefinitions().definitions.map(each => each.doc);
   const builtIn = astryx.filter(doc => doc.builtIn).map(doc => doc.name);
+  const order = choice.status === 'selected' ? (choice.order ?? []) : [];
+  const unchosen = choice.status === 'ambiguous' && !choice.configured;
   return {
     type: 'icon.list',
     data: {
@@ -28,7 +35,19 @@ export async function iconList({cwd}) {
         ? `${choice.set.package}/${choice.set.name}`
         : null,
       reason: choice.reason,
+      order: order.map(iconSetKey),
+      backups: (choice.backups ?? []).map(each => ({
+        iconSet: each.selector,
+        status: each.status,
+        reason: each.reason,
+      })),
+      ...(unchosen
+        ? {
+            next: `${sets.length} icon sets are installed and none is your main set: run \`${ICON_USE_ORDER_COMMAND}\`.`,
+          }
+        : {}),
       sets: sets.map(set => {
+        const rank = order.indexOf(set);
         const mapped = new Set(Object.keys(set.data.map ?? {}));
         return {
           name: set.name,
@@ -52,6 +71,13 @@ export async function iconList({cwd}) {
             own: set.definitions.map(each => each.doc.name),
           },
           project: set === choice.set,
+          role:
+            rank === 0
+              ? /** @type {const} */ ('main')
+              : rank > 0
+                ? /** @type {const} */ ('backup')
+                : null,
+          rank: rank === -1 ? null : rank + 1,
         };
       }),
       withdrawn: withdrawn.map(each => ({