@featherk/icons 0.14.1 → 0.15.0

package/dist/fontawesome/vite.cjs

@@ -2,7 +2,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const node_path = require("node:path");
 const promises = require("node:fs/promises");
-const generate = require("./chunks/generate-Bobf_ghm.cjs");
+const fontawesome_catalog = require("./catalog.cjs");
+const generate = require("./chunks/generate-BBurrhLv.cjs");
 const virtualId = "virtual:featherk/fontawesome";
 const resolvedId = `\0${virtualId}`;
 function dependencyKey(file) {
@@ -15,9 +16,10 @@ function featherkFontAwesome(options) {
   let dependencies = /* @__PURE__ */ new Set();
   function regenerate() {
     generation = generate.generateFaIcons({
-      icons: options.icons,
+      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));
@@ -30,6 +32,15 @@ function featherkFontAwesome(options) {
     enforce: "pre",
     async configResolved(config) {
       root = node_path.resolve(config.root, options.root ?? ".");
+      const installCommand = options.keys === void 0 ? void 0 : fontawesome_catalog.getFontAwesomeInstallCommand(options.keys, {
+        allowPro: options.allowPro
+      });
+      if (installCommand) {
+        console.info(
+          `[featherk-fontawesome] Install selected source packages with:
+${installCommand}`
+        );
+      }
       await regenerate();
     },
     async buildStart() {

package/dist/fontawesome/vite.d.ts

@@ -1,6 +1,13 @@
 import type { Plugin } from "vite";
 import type { FontAwesomeOptions } from "./types";
+/** Configuration for the Font Awesome virtual module plugin. */
 export interface FontAwesomeViteOptions extends FontAwesomeOptions {
     virtualTypesFile?: string | false;
 }
+/**
+ * Creates the Vite plugin for `virtual:featherk/fontawesome`.
+ *
+ * Catalog keys are resolved during Vite config setup, and their license
+ * notices are emitted into production builds.
+ */
 export declare function featherkFontAwesome(options: FontAwesomeViteOptions): Plugin;

package/dist/fontawesome/vite.mjs

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { realpath } from "node:fs/promises";
-import { g as generateFaIcons } from "./chunks/generate-Bp92GTVi.mjs";
+import { getFontAwesomeInstallCommand } from "./catalog.mjs";
+import { g as generateFaIcons } from "./chunks/generate-Zq9q2YZD.mjs";
 const virtualId = "virtual:featherk/fontawesome";
 const resolvedId = `\0${virtualId}`;
 function dependencyKey(file) {
@@ -13,9 +14,10 @@ function featherkFontAwesome(options) {
   let dependencies = /* @__PURE__ */ new Set();
   function regenerate() {
     generation = generateFaIcons({
-      icons: options.icons,
+      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));
@@ -28,6 +30,15 @@ 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();
     },
     async buildStart() {

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-06T00:13:29.670Z
+> Generated: 2026-10-06T20:52:21.447Z

package/docs/fontawesome/CreateFontAwesomeManifest.md

@@ -1,28 +1,31 @@
 # Choose Font Awesome Icons and Create a Manifest
 
-This is the UX/Design starting point for choosing the exact Font Awesome variants an application intends to use and recording them in its selection manifest. It covers icon selection, approval, naming, and manifest fields. For integration and build setup, continue to [Font Awesome Build Integration](FontAwesome.md); CLI and non-Vite workflows are in [the CLI supplement](FontAwesomeCLI.md).
+This guide covers how the UX Team designates needed Font Awesome variants, how the FeatherK UX/Design Engineer maintains the published metadata catalog, and how an application selects only the icons it uses. The published catalog is the shared source of truth and contains metadata, not artwork. A consuming app needs only the UX-provided keys; Vite resolves those keys without requiring the app to import or inspect other catalog entries. For integration and build setup, continue to [Font Awesome Build Integration](FontAwesome.md); CLI and non-Vite workflows are in [the CLI supplement](FontAwesomeCLI.md).
 
 ## Quick Start
 
-1. Select the exact catalog icon, family, and style; note whether the variant is Free or Pro.
-2. Agree on the exact release and obtain the required UX and license approvals.
-3. Assign a unique application key and identify the package that supplies the variant and release.
-4. Add or update the selection in the application's manifest and review the full selection set.
+1. UX identifies the needed icon and intended family/style; confirm whether the variant is Free or Pro.
+2. The FeatherK UX/Design Engineer confirms the exact identity, release, and source mapping, and assigns a globally unique catalog key.
+3. The FeatherK UX/Design Engineer adds the variant metadata to the catalog and publishes the `@featherk/icons` update.
+4. The consuming application's Dev puts only the needed keys in its keys-only manifest and configures the Vite/CLI build; Pro sources still require authorized access and license coverage.
 
 The steps below help UX/Design create a precise handoff. Do not assume every icon exists in every family, style, or release.
 
 ## Where Each Field Comes From
 
-| Field     | Who supplies it                         | Meaning                                                                                                             |
-| --------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `key`     | UX/application convention               | Unique application lookup identifier, such as `pro-house-light`; passed to `getFaIcon()`                            |
-| `name`    | Font Awesome catalog                    | Canonical icon name, such as `house`, without the `fa-` CSS prefix                                                  |
-| `version` | Approved release policy                 | Exact source-package release, such as `7.0.0`, not `latest`, a range, or the first version that introduced the icon |
-| `family`  | Selected Font Awesome family            | Supported family identifier, such as `classic` or `sharp`                                                           |
-| `style`   | Selected Font Awesome style             | Supported style identifier, such as `solid`, `regular`, or `light`                                                  |
-| `package` | Engineering confirms the source mapping | Exact installed package name or alias that supplies the selected family, style, and version                         |
+| 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                   |
 
-The catalog identifies the canonical `name`, `family`, `style`, and Free/Pro availability. UX/Design proposes the application `key` and approved release. Engineering confirms the exact npm package or alias for `package`; Dev installs that package at the manifest's exact `version`. Do not guess package names. A catalog page alone does not establish historical release availability or license 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.
 
 ## Step 1: Select and Approve the Catalog Variant
 
@@ -37,7 +40,7 @@ Copied markup can help identify the selection:
 
 For this example, the canonical name is `heart`, family is `classic`, and style is `regular`. Confirm those values for the desired release; old CSS names may be compatibility aliases rather than that release's canonical name.
 
-UX should hand off the catalog link, canonical name, approved exact release, family, style, and approval record. Agree on an application key separately. Any package/download entitlement must also be confirmed for Pro.
+UX should hand off the catalog link, canonical name, approved exact release, family, style, and intended appearance. The FeatherK UX/Design Engineer assigns the catalog key and verifies the source mapping. Any package/download entitlement must also be confirmed for Pro.
 
 Important distinctions:
 
@@ -63,47 +66,37 @@ Common Classic package mappings are:
 
 The `classic`/`brands` rows show common package mappings. Other families include `sharp`, `duotone`, and `sharp-duotone`; confirm their package names and release availability in the [official package documentation](https://docs.fontawesome.com/web/setup/packages). Do not construct package names by guesswork. Pro+ collections requiring Kits are outside this integration.
 
-For Pro variants, confirm entitlement and release approval with the license owner before adding them. See [Pro licensing and setup](LICENSING.md). Engineering should confirm that the package recorded in the manifest is installed and supplies the requested variant.
+For Pro variants, confirm entitlement and release approval with the license owner before adding them. See [Pro licensing and setup](LICENSING.md). The FeatherK UX/Design Engineer verifies the package mapping in the catalog; consuming-app Dev installs the package for selected keys.
 
-## Step 3: Write the Complete Manifest Entry
+## Step 3: Select Keys in the Application Manifest
 
-Add the selection to an `icons` array. The filename is project-owned; this example uses a Free selection manifest:
+The FeatherK catalog holds the complete metadata record. A consuming app lists only the keys it actually uses; it does not repeat icon names, versions, styles, or package mappings. One project-owned keys file can group Free and optional Pro selections:
 
 ```json
 {
-  "icons": [
-    {
-      "key": "heart-outline",
-      "name": "heart",
-      "version": "7.0.0",
-      "family": "classic",
-      "style": "regular",
-      "package": "@fortawesome/free-regular-svg-icons"
-    }
-  ]
+  "free": ["heart-regular"],
+  "pro": []
 }
 ```
 
-This example records the selected Pro variant. In this repository, Free selections live in `demos/fontawesome.icons.json` and optional licensed selections in `demos/fontawesome.pro.icons.json`; other applications may choose their own manifest filenames.
-
-The `key` is the application's identifier and does not need to match the canonical `name`. Use a unique key for each distinct selection. For example, the same canonical icon can be selected with different styles or versions as long as each entry has a different key.
+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`.
 
 ## Naming and Uniqueness Rules
 
-The generator only requires `key` to be a nonblank string; it does not enforce a casing or punctuation style. For readability, UX/Design should use lowercase kebab-case and choose a stable, descriptive key:
+The catalog requires each `key` to be unique across all published variants. UX/Design Engineer assigns stable, descriptive lowercase kebab-case keys:
 
 - Use the canonical icon name as the key when only one variant is selected, such as `rocket`.
 - Add the style when the application needs multiple variants, such as `heart-regular` or `feather-light`.
 - Add a version suffix only when multiple releases must coexist, such as `rocket-v5` and `rocket-v6`.
-- Do not reuse a key for a different icon identity. If the selected variant changes, review the key and all application references with Engineering.
-- Check keys across every manifest enabled together in a build, including combined Free and Pro selections. A key repeated in separate files is still a duplicate when those files are combined.
+- Never reuse a key for a different identity. If the exact variant changes, assign/review a catalog key and update consumers with UX.
+- Use distinct keys for different styles or releases of the same canonical name.
 
-These are UX naming conventions; only blank and duplicate keys are rejected by the generator. The application uses the key for lookup, while `name`, `family`, `style`, `version`, and `package` identify the source artwork.
+Consumers use the UX-provided key for lookup. They do not need to know the other catalog entries or carry source metadata in their app manifest.
 
 ## UX/Design Handoff
 
-For each selection, provide the catalog link, canonical name, family, style, exact approved version, application key, Free/Pro status, and package mapping. UX/Design owns the desired variants and manifest change; Engineering confirms that the exact package and release are available and implements the build integration.
+The UX Team designates the desired icon and exact variant and provides its catalog link and intended appearance. The FeatherK UX/Design Engineer maintains the owned custom icon collection and published Font Awesome metadata catalog, assigns the globally unique key, and publishes package updates. For an application build, Dev selects only the needed keys in `vite.config.ts` or the shared keys-only file and owns source-package installation and build integration.
 
-Catalog approval and source availability are separate. If Engineering cannot resolve the requested package, version, or export, do not silently substitute another icon or release. Return to UX/Design and update the approval and manifest together.
+Catalog metadata and source availability or license entitlement are separate. A Pro key requires explicit Pro-profile opt-in and an authorized, exact source package. If the exact package, version, or export cannot be confirmed, fail the build rather than silently substituting another icon or release.
 
 After the manifest is ready, continue with [Vite build integration](FontAwesome.md). For Pro selections, review [Pro licensing and setup](LICENSING.md). Non-Vite or pre-typecheck CLI workflows are documented in [the CLI supplement](FontAwesomeCLI.md).

package/docs/fontawesome/FontAwesome.md

@@ -1,51 +1,35 @@
 # Font Awesome Build Integration
 
-Font Awesome support is opt-in. To use Font Awesome icons, Dev configures this build workflow to generate Kendo-compatible descriptors from the npm packages named by each manifest's `package` and exact `version` fields. UX/Design owns choosing the desired icon variants and recording them in the manifest; start with [Choose Font Awesome Icons and Create a Manifest](CreateFontAwesomeManifest.md). Consumers using only `getCustomIcon()` do not need this integration. `@featherk/icons` contains no Font Awesome artwork, Free or paid, and does not supply a license or authentication token.
+Font Awesome support is opt-in. `@featherk/icons` publishes one metadata-only catalog of FeatherK-curated Free and Pro variants at `@featherk/icons/fontawesome/catalog`; it contains no Font Awesome artwork and grants no license or access. UX provides globally unique catalog keys. A consuming app lists only keys it uses in its keys-only manifest and configures this workflow to generate Kendo-compatible descriptors from its authorized, installed sources. Consumers using only `getCustomIcon()` do not need this integration; that custom-icon API and registry remain separate.
 
-Once UX/Design has supplied the approved manifest, Dev owns source installation, Vite configuration, validation, and application integration. For licensed sources, see [Pro licensing and setup](LICENSING.md), including optional local profiles, secret handling, GitHub Actions/TeamCity, and consuming applications.
+The FeatherK UX/Design Engineer maintains the published catalog; the UX Team designates requested icons and variants. Consuming-app Dev owns key selection, source installation, Vite configuration, validation, and application integration. For licensed sources, see [Pro licensing and setup](LICENSING.md), including optional local profiles, secret handling, GitHub Actions/TeamCity, and consuming applications.
 
 ## Quick Start
 
-1. UX/Design selects and approves each exact icon variant and records it in the [manifest](CreateFontAwesomeManifest.md); the license owner confirms Pro entitlement and approved release coverage.
+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 confirms access and availability for each manifest `package` and exact `version`, configures authorized registry access when required, then installs those 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 to use the approved manifest and validates the installed selections in [Vite Setup](#vite-setup).
+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).
 
-This Free example uses an illustrative `fa-solid-v7` installed alias. Resolve its actual package, availability, version, and entitlement before use. 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).
+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).
 
 ```json
 {
-  "icons": [
-    {
-      "key": "account",
-      "name": "user",
-      "version": "7.0.0",
-      "family": "classic",
-      "style": "solid",
-      "package": "fa-solid-v7"
-    }
-  ]
+  "free": ["user"],
+  "pro": []
 }
 ```
 
 ### Pro Demo Example
 
-The repository's Pro demo selects Classic Light `house` from Font Awesome Pro 7 and exposes it with the manifest key `pro-house-light`. Use this selection only when the application has the required Font Awesome Pro access and license coverage:
+The repository's Pro demo selects Classic Light `house` from Font Awesome Pro 7 with the catalog key `pro-house-light`. Include it only in an authorized Pro build with the required package access and license coverage:
 
 ```json
 {
-  "icons": [
-    {
-      "key": "pro-house-light",
-      "name": "house",
-      "version": "7.0.0",
-      "family": "classic",
-      "style": "light",
-      "package": "@fortawesome/pro-light-svg-icons"
-    }
-  ]
+  "free": ["user"],
+  "pro": ["pro-house-light"]
 }
 ```
 
@@ -75,62 +59,65 @@ npm install --save-dev @featherk/icons vite@^7.0.0
 
 ## Install Source Packages
 
-Dev installs the npm package or alias named by each UX-approved manifest `package` field, pinned to that entry's exact `version`. The Free example uses the `fa-solid-v7` alias shown in the manifest; the Pro example installs `@fortawesome/pro-light-svg-icons@7.0.0` as recorded in its manifest entry and requires authorized Font Awesome package access before installation.
+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 alias used by the example manifest.
-npm install --save-dev --save-exact fa-solid-v7@npm:@fortawesome/free-solid-svg-icons@7.0.0
+# 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
 ```
 
-The Free command uses an alias to match the example manifest.
-
-Note: Aliases (i.e Like `fa-solid-v7` in the example above) let one project install multiple versions of the same npm package under distinct dependency names. See [alias details](#about-aliases-and-why-use-them).
+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.
+
 ## Vite Setup
 
-The following setup is Dev-owned and assumes the UX-approved manifest and required license approvals are in place.
+The following setup is Dev-owned and assumes the app keys-only manifest and required license approvals are in place.
 
 ```ts
 import { defineConfig } from "vite";
 import vue from "@vitejs/plugin-vue";
 import { featherkFontAwesome } from "@featherk/icons/fontawesome/vite";
-import type { FontAwesomeSelection } from "@featherk/icons/fontawesome";
-import manifest from "./fontawesome.icons.json";
+import manifest from "./fontawesome.keys.json";
+
+const proEnabled = process.env.FEATHERK_FONTAWESOME_PRO === "1";
 
-// Step 1: Use the UX-approved manifest and verify required entitlement.
+// 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 the npm packages matching each manifest package and version before Vite starts.
+// Step 3: Install source packages mapped by the selected catalog keys before Vite starts.
 export default defineConfig({
-  // Step 4: Use the selections from the manifest approved and installed above.
+  // Step 4: Pro keys are included only for the explicitly enabled profile.
   plugins: [
     vue(),
     featherkFontAwesome({
-      icons: manifest.icons as FontAwesomeSelection[],
+      keys: [...manifest.free, ...(proEnabled ? manifest.pro : [])],
+      allowPro: proEnabled,
+      sourceRoot: proEnabled ? "pro" : undefined,
     }),
   ],
 });
 ```
 
-Enable JSON imports in the consumer's TypeScript configuration if necessary. The assertion above supplies TypeScript's selection type; the generator still validates the manifest's supported fields and resolved identities at runtime.
+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.
 
 ### Render the Selected Key
 
 ```vue
 <template>
   <!-- Step 5: Render the generated descriptor directly through Kendo. -->
-  <SvgIcon :icon="accountIcon" />
+  <SvgIcon :icon="userIcon" />
 </template>
 
 <script setup lang="ts">
 import { SvgIcon } from "@progress/kendo-vue-common";
 import { getFaIcon } from "virtual:featherk/fontawesome";
 
-const accountIcon = getFaIcon("account");
+const userIcon = getFaIcon("user");
 </script>
 ```
 
@@ -144,7 +131,7 @@ The plugin emits `featherk-fontawesome.licenses.txt` into Vite build output (Ste
 
 `getFaIcon(key)` returns a runtime `FontAwesomeIcon` object with `{ name, content, viewBox }`, structurally compatible with Kendo's `SVGIcon`. `name` is the selected manifest key, `content` is the inner SVG path markup without an outer `<svg>`, and `viewBox` preserves the source geometry. The property is case-sensitive: `viewBox`, not `viewbox`.
 
-The following examples assume `rocket` is included in the project's enabled selections. Replace it with your selected key, such as `account` in the Quick Start manifest.
+The following examples assume `rocket` is included in the project's enabled selections. Replace it with your selected key, such as `user` in the Quick Start manifest.
 
 ### Application Code
 

package/docs/fontawesome/FontAwesomeCLI.md

@@ -1,16 +1,16 @@
 # Font Awesome CLI and Non-Vite Setup
 
-This Dev-owned supplement assumes UX/Design has supplied the approved selections in a manifest. For icon choice, approval, naming, and manifest authoring, 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 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).
 
 ## Quick Start
 
-1. Receive the UX-approved manifest and required license approvals.
+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 the npm package or alias named by each manifest `package` field at its exact `version` using authorized package access. 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 manifest.
+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.
 
-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.
+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.
 
 ### Generate declarations before a Vite type check
 
@@ -18,10 +18,10 @@ The Vite plugin writes `src/featherk-fontawesome.d.ts` on startup by default. If
 
 ```sh
 # Step 4: Generate the virtual-module declarations before standalone type checking.
-npm exec -- featherk-fontawesome --manifest fontawesome.icons.json --virtual-types src/featherk-fontawesome.d.ts
+npm exec -- featherk-fontawesome --manifest fontawesome.keys.json --virtual-types src/featherk-fontawesome.d.ts
 ```
 
-Configure `featherkFontAwesome` with the same selections. The CLI and plugin must use the same manifest; do not maintain conflicting selection lists. `virtualTypesFile` can select another project-local `.d.ts` path or disable plugin writing with `false`.
+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`.
 
 ### Generate a module for a non-Vite application
 
@@ -29,7 +29,7 @@ No migration to Vite is required. Generate a regular ESM module and adjacent dec
 
 ```sh
 # Step 4: Generate application-local ESM output from the selected manifest.
-npm exec -- featherk-fontawesome --manifest fontawesome.icons.json --out src/generated/fontawesome/icons.mjs
+npm exec -- featherk-fontawesome --manifest fontawesome.keys.json --out src/generated/fontawesome/icons.mjs
 ```
 
 Import the generated module before running the existing application build:
@@ -38,16 +38,16 @@ Import the generated module before running the existing application build:
 // Step 5: Use the manifest key selected for this application.
 import { getFaIcon } from "./generated/fontawesome/icons.mjs";
 
-const accountIcon = getFaIcon("account");
+const userIcon = getFaIcon("user");
 ```
 
 Run generation again when selections change, including before local development. A generation failure exits nonzero and must stop CI; do not continue with prior output. Preserve the emitted `icons.mjs.licenses.txt` notice in application distribution. Non-Vite bundlers do not automatically copy that sidecar.
 
 ## Node API and CLI Options
 
-`generateFaIcons` from `@featherk/icons/fontawesome/build` accepts `icons`, optional `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.
+`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`, `--source-root`, `--out`, `--virtual-types`, and `--help`. The manifest must contain an `icons` array; 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.
 
 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.
 

package/docs/fontawesome/LICENSING.md

@@ -105,9 +105,9 @@ Two supported Vite layouts are:
 
 For non-Vite applications or declaration generation before a standalone type check, follow [CLI and non-Vite setup](FontAwesomeCLI.md). Registry authentication still belongs to the authorized package installation environment; the generator and browser never receive the token.
 
-For Vite, use `featherkFontAwesome({ icons, sourceRoot: "pro" })`. The profile scripts above are repository demo helpers, not scripts automatically installed into consumer applications.
+For Vite, pass only selected catalog keys and opt in at the profile level, for example `featherkFontAwesome({ keys, allowPro: true, sourceRoot: "pro" })`. Keep Pro keys in the app's optional Pro group and include them only in an authorized build profile. The profile scripts above are repository demo helpers, not scripts automatically installed into consumer applications. The `allowPro` option prevents accidental selection; it does not verify license entitlement.
 
-For applications using both Free and Pro, UX/Design approves both selection sets; Dev enables them together in the build manifest. Optional profiles must not silently include paid inputs in public/uncredentialed builds. Follow the [generated-output ignore guidance](FontAwesome.md#generated-output-and-source-checks): exclude generated files from ESLint/Prettier/Git while retaining TypeScript checks.
+For applications using both Free and Pro, UX provides catalog keys for both tiers; Dev keeps Free and Pro keys in the shared keys-only selection file and includes Pro keys only in the explicit authorized profile. Optional profiles must not silently include paid inputs in public/uncredentialed builds. Follow the [generated-output ignore guidance](FontAwesome.md#generated-output-and-source-checks): exclude generated files from ESLint/Prettier/Git while retaining TypeScript checks.
 
 ## CI and Deployment
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/icons",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "main": "dist/featherk-icons.umd.js",
   "module": "dist/featherk-icons.es.js",
   "types": "dist/index.d.ts",
@@ -25,6 +25,11 @@
       "import": "./dist/fontawesome/vite.mjs",
       "require": "./dist/fontawesome/vite.cjs"
     },
+    "./fontawesome/catalog": {
+      "types": "./dist/fontawesome/catalog.d.ts",
+      "import": "./dist/fontawesome/catalog.mjs",
+      "require": "./dist/fontawesome/catalog.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [