@featherk/icons 0.15.8 → 0.16.1

package/dist/fontawesome/vite.mjs

@@ -1,7 +1,7 @@
-import { resolve } from "node:path";
+import { resolve, relative } from "node:path";
 import { realpath } from "node:fs/promises";
-import { getFontAwesomeInstallCommand } from "./catalog.mjs";
-import { g as generateFaIcons } from "./chunks/generate-Zq9q2YZD.mjs";
+import { g as generateFaIcons, s as summarizeFaIcons } from "./chunks/generate-DF9R65sV.mjs";
+import { f as fontAwesomeProSourcesDir, r as readFontAwesomeManifest, s as selectFontAwesomeManifestKeys } from "./chunks/manifest-CF473fsM.mjs";
 const virtualId = "virtual:featherk/fontawesome";
 const resolvedId = `\0${virtualId}`;
 function dependencyKey(file) {
@@ -9,20 +9,56 @@ function dependencyKey(file) {
   return process.platform === "win32" ? path.toLowerCase() : path;
 }
 function featherkFontAwesome(options) {
+  const legacy = options;
+  if (legacy.keys !== void 0 || legacy.allowPro !== void 0) {
+    throw new Error(
+      'Font Awesome Vite options "keys" and "allowPro" were removed in 0.16.0. List the keys in a { free, pro } manifest and pass { manifest: "fontawesome.keys.json" }.'
+    );
+  }
+  if (legacy.sourceRoot !== void 0 || legacy.proMode !== void 0) {
+    throw new Error(
+      `Font Awesome Vite options "sourceRoot" and "proMode" were removed in 0.16.0. Pro sources always live in ${fontAwesomeProSourcesDir}/ and are used wherever it is installed; pass only { manifest }.`
+    );
+  }
+  if (typeof options.manifest !== "string" || !options.manifest.trim()) {
+    throw new Error(
+      'Font Awesome Vite options require a manifest path, such as { manifest: "fontawesome.keys.json" }'
+    );
+  }
   let root = resolve(options.root ?? process.cwd());
+  let logger;
   let generation;
   let dependencies = /* @__PURE__ */ new Set();
-  function regenerate() {
-    generation = generateFaIcons({
-      keys: options.keys,
-      root,
-      sourceRoot: options.sourceRoot,
-      allowPro: options.allowPro,
-      virtualTypesFile: options.virtualTypesFile === false ? void 0 : options.virtualTypesFile ?? "src/featherk-fontawesome.d.ts"
-    }).then((result) => {
-      dependencies = new Set(result.dependencies.map(dependencyKey));
+  let watchFiles = [];
+  async function resolveSelection() {
+    const manifestFile = resolve(root, options.manifest);
+    const manifest = await readFontAwesomeManifest(manifestFile).catch(
+      (error) => {
+        throw new Error(
+          `Cannot read Font Awesome manifest ${relative(root, manifestFile) || manifestFile}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    );
+    return {
+      ...selectFontAwesomeManifestKeys(manifest, root),
+      // Match the real paths that handleHotUpdate compares against.
+      manifestFile: await realpath(manifestFile)
+    };
+  }
+  function regenerate(selection) {
+    generation = (async () => {
+      const selected = selection ?? await resolveSelection();
+      const result = await generateFaIcons({
+        keys: selected.keys,
+        root,
+        sourceRoot: selected.sourceRoot,
+        allowPro: selected.allowPro,
+        virtualTypesFile: options.virtualTypesFile === false ? void 0 : options.virtualTypesFile ?? "src/featherk-fontawesome.d.ts"
+      });
+      watchFiles = [...result.dependencies, selected.manifestFile];
+      dependencies = new Set(watchFiles.map(dependencyKey));
       return result;
-    });
+    })();
     return generation;
   }
   return {
@@ -30,20 +66,12 @@ function featherkFontAwesome(options) {
     enforce: "pre",
     async configResolved(config) {
       root = resolve(config.root, options.root ?? ".");
-      const installCommand = options.keys === void 0 ? void 0 : getFontAwesomeInstallCommand(options.keys, {
-        allowPro: options.allowPro
-      });
-      if (installCommand) {
-        console.info(
-          `[featherk-fontawesome] Install selected source packages with:
-${installCommand}`
-        );
-      }
-      await regenerate();
+      if (config.command === "build") logger = config.logger;
+      await regenerate(await resolveSelection());
     },
     async buildStart() {
-      const result = await regenerate();
-      for (const file of result.dependencies) this.addWatchFile(file);
+      await regenerate();
+      for (const file of watchFiles) this.addWatchFile(file);
     },
     resolveId(id) {
       return id === virtualId ? resolvedId : void 0;
@@ -53,14 +81,14 @@ ${installCommand}`
       return (await (generation ?? regenerate())).moduleCode;
     },
     async configureServer(server) {
-      const result = await (generation ?? regenerate());
-      server.watcher.add(result.dependencies);
+      await (generation ?? regenerate());
+      server.watcher.add(watchFiles);
     },
     async handleHotUpdate(context) {
       const file = await realpath(context.file).catch(() => context.file);
       if (!dependencies.has(dependencyKey(file))) return void 0;
-      const result = await regenerate();
-      context.server.watcher.add(result.dependencies);
+      await regenerate();
+      context.server.watcher.add(watchFiles);
       const module = context.server.moduleGraph.getModuleById(resolvedId);
       if (module) context.server.moduleGraph.invalidateModule(module);
       context.server.ws.send({ type: "full-reload" });
@@ -75,6 +103,14 @@ ${installCommand}`
           source: result.notices
         });
       }
+    },
+    async closeBundle() {
+      const result = await generation?.catch(() => void 0);
+      if (logger && result) {
+        logger.info(
+          `[featherk-fontawesome] Generated ${summarizeFaIcons(result.provenance)}`
+        );
+      }
     }
   };
 }

package/docs/ADDING-ICONS.md

@@ -10,8 +10,8 @@ iconography repository provides validation tools for its source assets.
 
 Keep the category directory and filename when copying an icon:
 
-| Source in `iconography` | Destination in this repository |
-| --- | --- |
+| Source in `iconography`            | Destination in this repository               |
+| ---------------------------------- | -------------------------------------------- |
 | `src/icons/<category>/ic_Name.svg` | `packages/icons/icon/<category>/ic_Name.svg` |
 
 For example, copy `src/icons/action/ic_Edit.svg` to
@@ -35,6 +35,7 @@ entire iconography repository.
    missing IDs, and duplicate filenames. The full check also enforces the 5 KB
    file-size limit. After changing the source inventory, refresh it with
    `npm run document:icons`.
+
 3. Copy the selected SVG files unchanged into the matching category directories
    under `packages/icons/icon/`. Create the destination category directory if
    needed. Do not copy generated package output in place of the SVG source
@@ -55,4 +56,4 @@ entire iconography repository.
 The package generator derives each public icon name from its filename by
 removing the `ic_` prefix and `.svg` extension, then lowercasing the remainder.
 For example, `ic_User_Profile.svg` becomes `user_profile`. Keep filenames
-unique across categories; the iconography validator checks this requirement.
+unique across categories; the iconography validator checks this requirement.

package/docs/COMING-SOON.md

@@ -6,12 +6,13 @@ notice. They were moved out of the main README to keep the public surface area
 stable while we iterate on behaviour and naming.
 
 Quick summary:
+
 - `getIconCssUrl` / `getIconCssUrlBase64` — convenience helpers that return a
-	wrapped `url("...")` string suitable for assigning directly to CSS
-	`background-image` (UTF‑8 and base64 variants respectively).
+  wrapped `url("...")` string suitable for assigning directly to CSS
+  `background-image` (UTF‑8 and base64 variants respectively).
 - `getIconDataUrlBase64` — base64-encoded data URL variant of `getIconDataUrl`.
 - Usage examples and small CSS snippets that simplify embedding icons as
-	backgrounds or masks in styles.
+  backgrounds or masks in styles.
 
 Please treat these helpers as unstable. If you rely on them, expect possible
 breaking changes in future releases and prefer the lower-level `getIconDataUrl`
@@ -30,20 +31,23 @@ import { getCustomIcon, getIconDataUrl } from "@featherk/icons";
 const search = getCustomIcon("search");
 const searchIconUrl = getIconDataUrl(search);
 // Provide it to CSS via a custom property (example only)
-document.documentElement.style.setProperty("--search-icon", `url("${searchIconUrl}")`);
+document.documentElement.style.setProperty(
+  "--search-icon",
+  `url("${searchIconUrl}")`,
+);
 ```
 
 ```css
 .button::after {
- content: "";
- display: inline-block;
- width: 1em;
- height: 1em;
- background: no-repeat center/contain var(--search-icon);
- /* Alternatively, to tint using current text color:
+  content: "";
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  background: no-repeat center/contain var(--search-icon);
+  /* Alternatively, to tint using current text color:
 	 mask: var(--search-icon) no-repeat center / contain;
 	 background-color: currentColor; */
- margin-left: 0.25rem;
+  margin-left: 0.25rem;
 }
 ```
 
@@ -53,7 +57,11 @@ If you prefer a ready-to-use CSS value, use `getIconCssUrl` (UTF‑8) or
 `getIconCssUrlBase64` (base64). Both return a wrapped `url("...")` string.
 
 ```ts
-import { getCustomIcon, getIconCssUrl, getIconCssUrlBase64 } from "@featherk/icons";
+import {
+  getCustomIcon,
+  getIconCssUrl,
+  getIconCssUrlBase64,
+} from "@featherk/icons";
 
 const arrowLeft = getCustomIcon("arrow_left");
 const arrowLeftBg = getIconCssUrl(arrowLeft);
@@ -74,6 +82,8 @@ import { getCustomIcon, getIconDataUrlBase64 } from "@featherk/icons";
 const search = getCustomIcon("search");
 const searchIconUrlBase64 = getIconDataUrlBase64(search);
 // Example: set as CSS background
-document.documentElement.style.setProperty("--search-icon", `url("${searchIconUrlBase64}")`);
+document.documentElement.style.setProperty(
+  "--search-icon",
+  `url("${searchIconUrlBase64}")`,
+);
 ```
-

package/docs/ICONS.md

@@ -211,4 +211,4 @@
 |rating_star_selected|switch_left|switch_off|switch_on|switch_right| |
 <!-- markdownlint-enable MD033-->
 
-> Generated: 2026-10-15T15:30:54.353Z
+> Generated: 2026-10-16T17:15:34.562Z

package/docs/fontawesome/CreateFontAwesomeManifest.md

@@ -13,17 +13,17 @@ The steps below help UX/Design create a precise handoff. Do not assume every ico
 
 ## Where Each Field Comes From
 
-| Catalog field | Who supplies it                         | Meaning                                                                                                             |
-| ------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `key`         | UX/Design Engineer                     | Stable, globally unique lookup key for exactly one catalog variant; supplied to Vite/CLI by the consumer            |
-| `name`        | Font Awesome catalog                    | Canonical icon name, such as `house`, without the `fa-` CSS prefix                                                  |
-| `version`     | UX and release approval                 | Exact source-package release, such as `7.0.0`, not `latest`, a range, or the first version that introduced the icon |
-| `family`      | UX/design selection                     | Supported family identifier, such as `classic` or `sharp`                                                           |
-| `style`       | UX/design selection                     | Supported style identifier, such as `solid`, `regular`, or `light`                                                  |
-| `package`     | UX/Design Engineer                      | Exact installed dependency name; may be an npm alias such as `fa-solid-v5`                                          |
-| `registryPackage` | UX/Design Engineer                  | Canonical npm package name targeted by `package` and checked against installed package metadata                    |
-| `exportName`  | UX/Design Engineer                      | Exact individual icon export in the source package                                                                 |
-| `tier`        | UX/Design Engineer                      | `free` or `pro` classification for the exact variant; descriptive only, not proof of entitlement                   |
+| Catalog field     | Who supplies it         | Meaning                                                                                                             |
+| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `key`             | UX/Design Engineer      | Stable, globally unique lookup key for exactly one catalog variant; supplied to Vite/CLI by the consumer            |
+| `name`            | Font Awesome catalog    | Canonical icon name, such as `house`, without the `fa-` CSS prefix                                                  |
+| `version`         | UX and release approval | Exact source-package release, such as `7.0.0`, not `latest`, a range, or the first version that introduced the icon |
+| `family`          | UX/design selection     | Supported family identifier, such as `classic` or `sharp`                                                           |
+| `style`           | UX/design selection     | Supported style identifier, such as `solid`, `regular`, or `light`                                                  |
+| `package`         | UX/Design Engineer      | Exact installed dependency name; may be an npm alias such as `fa-solid-v5`                                          |
+| `registryPackage` | UX/Design Engineer      | Canonical npm package name targeted by `package` and checked against installed package metadata                     |
+| `exportName`      | UX/Design Engineer      | Exact individual icon export in the source package                                                                  |
+| `tier`            | UX/Design Engineer      | `free` or `pro` classification for the exact variant; descriptive only, not proof of entitlement                    |
 
 Each catalog key identifies one exact name/version/family/style/package/export variant. Different styles or releases require different keys. Catalog records are maintained and published by FeatherK; consuming applications do not copy these fields into their selection manifest. `tier` describes the Font Awesome product tier only; it does not grant access or establish license coverage. Package availability and Pro entitlement must still be confirmed independently.
 
@@ -79,7 +79,7 @@ The FeatherK catalog holds the complete metadata record. A consuming app lists o
 }
 ```
 
-For an optional Pro build, put its requested catalog keys in `pro`. Vite/CLI include those keys only when the app explicitly enables its authorized Pro profile. In this repository the shared key file is `demos/fontawesome.keys.json`.
+Put Pro catalog keys in `pro`; a Pro key listed under `free` is rejected. The setup command installs Pro keys into the private `fontawesome-pro-sources/` project, and Vite and the CLI generate them wherever that project is installed (see [Quick Start](FontAwesome.md#quick-start)). In this repository the shared key file is `demos/fontawesome.keys.json`.
 
 ## Naming and Uniqueness Rules
 

package/docs/fontawesome/FontAwesome.md

@@ -6,21 +6,35 @@ The FeatherK UX/Design Engineer maintains the published catalog; the UX Team des
 
 ## Quick Start
 
-1. UX designates the needed exact icon variant; the FeatherK UX/Design Engineer maintains its globally unique key and exact metadata in the published catalog. The license owner confirms Pro entitlement and approved release coverage.
-2. Dev installs `@featherk/icons` with the Font Awesome Vite entry point and ensures compatible Vite 7.x or 8.x is available using [Install the Vite Integration](#install-the-vite-integration).
-3. Dev checks the source mapping for selected keys, confirms access and availability, configures authorized registry access when required, then installs only the matching pinned npm packages using [Install Source Packages](#install-source-packages). For Pro, follow [Pro token setup](LICENSING.md#dev-setup-quick-start) before installation.
-4. Dev configures the Vite plugin with only the selected keys. Pro keys require explicit Pro-profile opt-in and authorized installed sources; see [Vite Setup](#vite-setup).
-5. Dev renders the selected descriptors through the virtual module using the [rendering example](#render-the-selected-key).
-6. Dev preserves emitted license notices in application distribution as described in [Preserve license notices](#preserve-license-notices).
+One keys-only manifest drives everything: the setup command installs exactly what it lists, and the Vite plugin generates exactly what it lists. For the full local and CI walkthrough, including TeamCity, see [FeatherK FontAwesome Developer Setup](FontAwesomeDeveloperSetup.md).
 
-Consumers need only the keys, not the other catalog records. These examples use keys present in the published catalog; verify source availability and license coverage for the project's exact selections. Install a FeatherK release/build containing these entry points; a prior published release does not gain them automatically. For CLI generation, including declaration preparation before an early type check, see [CLI and non-Vite setup](FontAwesomeCLI.md).
+1. **Create the manifest.** Put the UX-provided catalog keys in `fontawesome.keys.json` at the application root (see [Choose Font Awesome Icons and Create a Manifest](CreateFontAwesomeManifest.md)). Pro keys go under `pro`, and the license owner confirms Pro entitlement first.
 
-```json
-{
-  "free": ["user"],
-  "pro": []
-}
-```
+   ```json
+   {
+     "free": ["user"],
+     "pro": []
+   }
+   ```
+
+2. **Install the packages.** From the application root, [install `@featherk/icons` and Vite](#install-the-vite-integration), then run the setup command with the same manifest. It pins Free packages into the application and Pro packages into a private `fontawesome-pro-sources/` project, at their exact catalog versions; with Pro keys, it prompts for the package token. Commit `fontawesome-pro-sources/` with the application. See [Pro licensing and setup](LICENSING.md#default-isolated-pro-sources).
+
+   ```sh
+   npx featherk-fontawesome-setup --manifest fontawesome.keys.json
+   # No Pro keys? Add --free-only: public npm only, no token.
+   ```
+
+3. **Add the plugin** to `vite.config.ts` with the same manifest:
+
+   ```ts
+   featherkFontAwesome({ manifest: "fontawesome.keys.json" });
+   ```
+
+4. **Build** with the application's normal `dev` and `build` scripts. Wherever `fontawesome-pro-sources/` is installed (step 2 locally, or the `npx featherk-fontawesome-setup` step in CI), builds include the Pro icons. Where it isn't installed, builds include only the Free icons.
+5. **Render icons** from the virtual module; see the [rendering example](#render-the-selected-key).
+6. **Preserve license notices** in application distribution; see [Preserve license notices](#preserve-license-notices).
+
+That is the whole recommended setup for Free-only and Free and Pro applications alike. Because Pro packages live in `fontawesome-pro-sources/`, the application's own install never needs the token. Type checks that run before Vite and projects that don't use Vite are covered under [Advanced setups](#advanced-setups).
 
 ### Pro Demo Example
 
@@ -35,7 +49,7 @@ The repository's Pro demo selects Classic Light `house` from Font Awesome Pro 7
 
 This follows the demo's Vite virtual-module flow. The Pro page filters generated provenance for `pro-` keys and passes the choices to its shared renderer; an application can also render this selected icon directly:
 
-```vue
+```html
 <template>
   <SvgIcon :icon="houseIcon" />
 </template>
@@ -80,55 +94,33 @@ npm install --save-dev @featherk/icons vite@^7.0.0
 
 ## Install Source Packages
 
-The catalog maps each key to its local dependency name, canonical registry package, export, and exact version. Dev installs only packages needed by selected keys, pinned to those exact versions. When Vite processes the selected keys, it prints one deduplicated `npm install --save-dev --save-exact ...` command in the terminal, including version aliases where needed. The CLI prints the same suggestion before generation. Run it from the consuming project with the appropriate registry access; FeatherK tooling never installs packages or handles credentials. During generation, the installed package's declared name is checked against `registryPackage` and its version against the catalog before the icon module is loaded. The Free example uses `@fortawesome/free-solid-svg-icons@7.0.0`; the Pro example needs authorized access to `@fortawesome/pro-light-svg-icons@7.0.0`.
-
-```sh
-# Free source for the selected `user` key.
-npm install --save-dev --save-exact @fortawesome/free-solid-svg-icons@7.0.0
-
-# Pro package used by the example manifest.
-npm install --save-dev --save-exact @fortawesome/pro-light-svg-icons@7.0.0
-```
+Run `featherk-fontawesome-setup --manifest fontawesome.keys.json` from the application root (Quick Start step 2). The catalog maps each key to its local dependency name, canonical registry package, export, and exact version, and the command installs only the packages the manifest needs, pinned to those versions, including npm aliases where one release must sit beside another (see [alias details](#about-aliases-and-why-use-them)). Free packages go into the application's `devDependencies`. Pro packages go into `fontawesome-pro-sources/`, whose `.npmrc` holds only a token placeholder, and the token is passed only to npm. On a fresh clone or in CI, run `npx featherk-fontawesome-setup` without arguments after the application's `npm ci` to install that project from its lockfile. See [Pro licensing and setup](LICENSING.md#consuming-applications) for the token, CI, TeamCity, and the `--free-only` exception. Never put a Pro token in a command or commit it.
 
-Aliases let one project install multiple versions of the same npm package under distinct dependency names. The catalog's `package` mapping specifies the dependency name for each selected version. See [alias details](#about-aliases-and-why-use-them).
-
-Never put a Pro token in the command or commit it. See [Pro licensing and setup](LICENSING.md) for secure registry configuration.
-
-The printed command is an install suggestion, not a license or access check. Pro builds still require separately configured authorized registry access and the explicit Pro profile. Vite may print the same selected-package command on each startup; it includes only packages mapped from that app's selected keys.
+During generation, the installed package's declared name is checked against `registryPackage` and its version against the catalog before the icon module is loaded. When a package is missing, generation fails with a message that points to the setup command; nobody installs Font Awesome packages by hand. At the end of each build, Vite logs the source packages the icons came from, for information only. The setup command is not a license or access check.
 
 ## Vite Setup
 
-The following setup is Dev-owned and assumes the app keys-only manifest and required license approvals are in place.
+Point the plugin at the manifest that `featherk-fontawesome-setup` installed from:
 
 ```ts
 import { defineConfig } from "vite";
 import vue from "@vitejs/plugin-vue";
 import { featherkFontAwesome } from "@featherk/icons/fontawesome/vite";
-import manifest from "./fontawesome.keys.json";
-
-const proEnabled = process.env.FEATHERK_FONTAWESOME_PRO === "1";
 
-// Step 1: Use UX-provided keys; verify any required Pro entitlement separately.
-// Step 2: Ensure @featherk/icons and Vite 7 or 8 are available.
-// Step 3: Install source packages mapped by the selected catalog keys before Vite starts.
 export default defineConfig({
-  // Step 4: Pro keys are included only for the explicitly enabled profile.
-  plugins: [
-    vue(),
-    featherkFontAwesome({
-      keys: [...manifest.free, ...(proEnabled ? manifest.pro : [])],
-      allowPro: proEnabled,
-      sourceRoot: proEnabled ? "pro" : undefined,
-    }),
-  ],
+  plugins: [vue(), featherkFontAwesome({ manifest: "fontawesome.keys.json" })],
 });
 ```
 
-Enable JSON imports in the consumer's TypeScript configuration if necessary. The app passes only keys; the catalog supplies exact metadata, and the generator validates installed source versions and identities at runtime.
+The plugin reads the manifest relative to the Vite project root and validates every key through the catalog. It always generates the `free` keys. When the project has `fontawesome-pro-sources/`, it adds the `pro` keys, resolved from that project, only when that project is installed (its `node_modules` exists); otherwise it never reads it. A build where the install was skipped is Free-only, and code that uses a Pro key then fails type checking, because the generated key union contains only Free keys. A manifest with `pro` keys in a project without `fontawesome-pro-sources/` fails with a message to run the setup command. A Pro-tier key listed under `free` is rejected with a message to move it to `pro`. Selecting keys this way is not license authorization. The plugin watches the manifest and reloads the dev server when it changes. The catalog supplies exact metadata, and the generator validates installed source versions and identities at runtime.
+
+### Upgrading from 0.15
+
+0.16.0 removed the plugin's `keys`, `allowPro`, and `sourceRoot` options; the setup command's `--keys`, `--source-root`, `--init`, `--force`, and `--refresh-lock`; and the CLI's `--allow-pro` and `--source-root`. Passing them fails with a message that explains the replacement. Move the keys into the manifest, pass `{ manifest }`, and rerun `featherk-fontawesome-setup --manifest fontawesome.keys.json`, which moves Pro packages into `fontawesome-pro-sources/`. Pro packages always live in `fontawesome-pro-sources/`; installing them into the application itself is not supported.
 
 ### Render the Selected Key
 
-```vue
+```html
 <template>
   <!-- Step 5: Render the generated descriptor directly through Kendo. -->
   <SvgIcon :icon="userIcon" />
@@ -181,8 +173,7 @@ The real `content` contains the complete path data; the abbreviated example is n
 While viewing the application on a running Vite dev server, inspect a descriptor from the browser console:
 
 ```js
-const { getFaIcon } =
-  await import("/@id/__x00__virtual:featherk/fontawesome");
+const { getFaIcon } = await import("/@id/__x00__virtual:featherk/fontawesome");
 
 console.log(getFaIcon("rocket"));
 ```
@@ -217,6 +208,14 @@ Keep this file covered by the project's TypeScript `include` patterns, such as `
 
 In the FeatherK monorepo, the exact root-relative pattern is `demos/src/featherk-fontawesome.d.ts`. ESLint's global ignores, `.prettierignore`, and `.gitignore` exclude that file; the demo TypeScript configuration still includes it. The generator, plugin, and handwritten declarations remain linted. If a type checker runs before Vite starts, see [CLI and non-Vite setup](FontAwesomeCLI.md) for declaration preparation. The library does not modify consumer lint configuration or inject ESLint-disable directives.
 
+## Advanced Setups
+
+Most applications need only the [Quick Start](#quick-start). Use these only when it doesn't fit.
+
+### Type Checks Before Vite, and Non-Vite Projects
+
+The plugin writes its declarations when Vite starts, which is too late for a `vue-tsc` or `tsc` step that runs first. Projects in that situation, and projects that don't use Vite, generate with the `featherk-fontawesome` CLI from the same manifest; see [CLI and non-Vite setup](FontAwesomeCLI.md). Custom Node tooling can call `generateFaIcons` from `@featherk/icons/fontawesome/build`, which takes resolved keys instead of a manifest.
+
 ## Supported Sources and Licensing
 
 ### Verified Free Consumer

package/docs/fontawesome/FontAwesomeCLI.md

@@ -1,41 +1,38 @@
 # Font Awesome CLI and Non-Vite Setup
 
-This Dev-owned supplement assumes UX/Design has supplied catalog keys. The catalog contains the source metadata; the app manifest contains only keys the project uses. For icon choice and key assignment, start with [Choose Font Awesome Icons and Create a Manifest](CreateFontAwesomeManifest.md). For the default Vite integration, see [Font Awesome Build Integration](FontAwesome.md).
+This is an advanced supplement. Most applications need only the Vite plugin; start with the [Quick Start](FontAwesome.md#quick-start). Use the `featherk-fontawesome` CLI when a type checker runs before Vite, or when the project doesn't use Vite.
 
-## Quick Start
+The CLI reads the same keys-only manifest as the setup command and the Vite plugin, and selects keys the same way:
 
-1. Receive the UX-provided catalog keys and required license approvals.
-2. Dev installs `@featherk/icons` at a release containing the CLI or Node API; for example, `npm install --save-dev @featherk/icons`.
-3. Dev installs only the packages mapped to selected keys in the published catalog, pinned to exact versions. For Pro, follow [Pro token setup](LICENSING.md#dev-setup-quick-start) before installation; package examples are in [Install Source Packages](FontAwesome.md#install-source-packages).
-4. Dev generates virtual-module declarations or a regular ESM module from the keys-only manifest.
-5. Dev imports the generated module where needed, type-checks declarations, and preserves emitted license notices.
+- When the project has `fontawesome-pro-sources/` (the [default setup](LICENSING.md#default-isolated-pro-sources)), it generates the `pro` keys from that project only when it is installed. Otherwise it generates the `free` keys alone.
+- Without `fontawesome-pro-sources/` (a Free-only setup), it generates the `free` keys; a manifest with `pro` keys then fails with a message to run the setup command.
 
-The CLI prints one deduplicated exact install command for the packages mapped to selected keys before generation. Run that command yourself from the consumer project after configuring any required registry access. The CLI validates installed Font Awesome source packages; it does not install them or authenticate with a registry. A prior FeatherK release does not gain the CLI or Node API entry points automatically.
+Install source packages first with `featherk-fontawesome-setup --manifest fontawesome.keys.json` ([Install Source Packages](FontAwesome.md#install-source-packages)). The CLI validates the installed packages; it does not install them or authenticate with a registry.
 
-### Generate declarations before a Vite type check
+## Generate Declarations Before a Vite Type Check
 
 The Vite plugin writes `src/featherk-fontawesome.d.ts` on startup by default. If `vue-tsc` or `tsc` runs before Vite starts, prepare that file first:
 
 ```sh
-# Step 4: Generate the virtual-module declarations before standalone type checking.
+# Generate the virtual-module declarations before standalone type checking.
 npm exec -- featherk-fontawesome --manifest fontawesome.keys.json --virtual-types src/featherk-fontawesome.d.ts
 ```
 
-The manifest uses `{ "free": ["key"], "pro": ["key"] }`. By default, the CLI selects only `free` keys. For a licensed profile, add `--allow-pro`; the CLI then includes the `pro` keys and rejects Pro selections if the exact source package cannot be resolved. Configure the Vite plugin with the same key file and profile. `virtualTypesFile` can select another project-local `.d.ts` path or disable plugin writing with `false`.
+The CLI and the Vite plugin check the same installed `fontawesome-pro-sources/`, so a declaration step that runs just before the build selects the same keys. The plugin's `virtualTypesFile` option can select another project-local `.d.ts` path or disable plugin writing with `false`.
 
-### Generate a module for a non-Vite application
+## Generate a Module for a Non-Vite Application
 
 No migration to Vite is required. Generate a regular ESM module and adjacent declarations/notices:
 
 ```sh
-# Step 4: Generate application-local ESM output from the selected manifest.
+# Generate application-local ESM output from the manifest.
 npm exec -- featherk-fontawesome --manifest fontawesome.keys.json --out src/generated/fontawesome/icons.mjs
 ```
 
 Import the generated module before running the existing application build:
 
 ```js
-// Step 5: Use the manifest key selected for this application.
+// Use a manifest key selected for this application.
 import { getFaIcon } from "./generated/fontawesome/icons.mjs";
 
 const userIcon = getFaIcon("user");
@@ -45,15 +42,13 @@ Run generation again when selections change, including before local development.
 
 ## Node API and CLI Options
 
-`generateFaIcons` from `@featherk/icons/fontawesome/build` accepts selected `keys`, optional `allowPro`, `root`, `sourceRoot`, `outFile`, and `virtualTypesFile`. It returns ESM code, file-module declarations, ambient virtual-module declarations, notices, provenance, and source dependency paths. Without output options, it writes nothing. Catalog keys are the only supported selection input. Pro keys require `allowPro: true`, which is an accidental-use guard, not proof of license entitlement.
+The CLI accepts `--manifest`, `--root`, `--out`, `--virtual-types`, and `--help`. The manifest contains a `free` array and an optional `pro` array of catalog keys; a Pro-tier key under `free` is rejected. `--allow-pro`, `--source-root`, and `--pro-mode` were removed in 0.16.0. Specify at least one output. Paths are relative to `--root` or the current directory. File output uses `.js`/`.mjs` with `.d.ts`/`.d.mts` declarations; ambient output uses `.d.ts` and must not overwrite the file-module declaration.
 
-The CLI accepts `--manifest`, `--root`, `--source-root`, `--allow-pro`, `--out`, `--virtual-types`, and `--help`. The manifest contains `free` and optional `pro` arrays of catalog keys; full-record `icons` manifests are rejected. To migrate from 0.14.0, replace each full selection record with its UX-provided catalog key and use the published catalog for source metadata. Specify at least one output. Paths are relative to `--root` or the current directory. File output uses `.js`/`.mjs` with `.d.ts`/`.d.mts` declarations; ambient output uses `.d.ts` and must not overwrite the file-module declaration.
+For custom Node tooling, `generateFaIcons` from `@featherk/icons/fontawesome/build` takes already-resolved `keys`, optional `allowPro`, `root`, `sourceRoot`, `outFile`, and `virtualTypesFile`. It returns ESM code, file-module declarations, ambient virtual-module declarations, notices, provenance, and source dependency paths, and writes nothing without output options. Pro keys require `allowPro: true`, which is an accidental-use guard, not proof of license entitlement. Prefer the CLI, which derives these, including `sourceRoot: "fontawesome-pro-sources"`, from the manifest and layout.
 
 Output must remain inside the consumer project, outside `node_modules` and the `@featherk/icons` package. The independent runtime `createFontAwesomeService` is available from `@featherk/icons/fontawesome`; Node tooling is never imported through the custom-icon root service.
 
-The API and Vite plugin accept `sourceRoot` to resolve installed packages from a separate source project without moving the output boundary. The CLI equivalent is `--source-root`. Relative source paths resolve from `root`; authentication still happens during npm installation, never in the generator or browser.
-
-To install source packages, use the separate `featherk-fontawesome-setup` command described in [Consuming Applications](LICENSING.md#consuming-applications). It supports the standard Free and Pro app-root setup, Free-only setup, and the isolated source project. The generator does not install anything; the setup command is the only FeatherK tool that receives the package token.
+A source root resolves installed packages from a separate source project without moving the output boundary. Relative source paths resolve from `root`; authentication still happens during npm installation, never in the generator or browser. The generator does not install anything; `featherk-fontawesome-setup` is the only FeatherK tool that receives the package token.
 
 ## Generated Output and Source Checks