@featherk/icons 0.15.8 → 0.16.0

package/dist/fontawesome/vite.d.ts

@@ -1,13 +1,34 @@
 import type { Plugin } from "vite";
-import type { FontAwesomeOptions } from "./types";
-/** Configuration for the Font Awesome virtual module plugin. */
-export interface FontAwesomeViteOptions extends FontAwesomeOptions {
+/**
+ * Configuration for the Font Awesome virtual module plugin. Selections come
+ * from the same keys-only `{ free, pro }` manifest used by
+ * `featherk-fontawesome-setup`.
+ *
+ * When the project has a `fontawesome-pro-sources/` source project (the
+ * default setup), the manifest's `pro` keys are generated from it only in
+ * builds where that project is installed. Otherwise every key comes from the
+ * project's own installed packages.
+ */
+export interface FontAwesomeViteOptions {
+    /** Keys-only manifest path, relative to the project root. */
+    manifest: string;
+    /** Project root, relative to Vite's root. */
+    root?: string;
     virtualTypesFile?: string | false;
+    /** Removed in 0.16.0; list keys in the manifest instead. */
+    keys?: never;
+    /** Removed in 0.16.0; Pro selection follows the manifest and layout. */
+    allowPro?: never;
+    /** Removed in 0.16.0; Pro sources always live in `fontawesome-pro-sources/`. */
+    sourceRoot?: never;
 }
 /**
  * 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.
+ * Keys are read from the manifest and resolved during Vite config setup, and
+ * their license notices are emitted into production builds. Mode gating
+ * selects which keys to generate; it is not license authorization.
+ *
+ * @throws If `manifest` is missing or a removed option is provided.
  */
 export declare function featherkFontAwesome(options: FontAwesomeViteOptions): Plugin;

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-CSRIDvaR.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/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-15T21:01:16.022Z

package/docs/fontawesome/CreateFontAwesomeManifest.md

@@ -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 token-scoped install 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
 
@@ -80,51 +94,29 @@ 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
-```
-
-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.
+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 `--pro-in-app` exception. Never put a Pro token in a command or commit it.
 
-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. An application set up with `--pro-in-app` has no such directory, so every build includes its `pro` keys from the application's own packages. 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/`. An application that installed Pro into its own dependencies keeps that layout with `--pro-in-app`.
 
 ### Render the Selected Key
 
@@ -217,6 +209,18 @@ 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.
+
+### Pro in the Application
+
+An application whose tooling cannot use the separate `fontawesome-pro-sources/` project can install Pro packages into its own dependencies with `featherk-fontawesome-setup --manifest fontawesome.keys.json --pro-in-app` (see [Exception: Pro in the Application](LICENSING.md#exception-pro-in-the-application)). The plugin options stay `{ manifest }`, and every build includes the Pro keys. The cost is that every install of the application, by every developer and CI job, then needs the token. Use it only with a real reason.
+
+### 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/` (Free-only or `--pro-in-app` setups), it generates every manifest key from the application's installed packages.
 
-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
 

package/docs/fontawesome/FontAwesomeDeveloperSetup.md

@@ -0,0 +1,134 @@
+# FeatherK FontAwesome Developer Setup
+
+This is the step-by-step setup for a developer adding Font Awesome icons to an application with `@featherk/icons`, on a local machine and in CI. It covers the default layout every team uses: Free packages in the application, Pro packages in a private `fontawesome-pro-sources/` project. For background, see [Font Awesome Build Integration](FontAwesome.md). For licensing, token handling, and the `--free-only` and `--pro-in-app` exceptions, see [Font Awesome Pro Licensing and Setup](LICENSING.md).
+
+## Before You Start
+
+- Confirm package access, release coverage, and Creator seats with the license owner. A package token enables downloads; it grants no license seats, and neither does `@featherk/icons`.
+- Get a Pro Package Token from the [Font Awesome Tokens page](https://fontawesome.com/account/tokens). Never put the token in a file, a command, or shell history. The setup command reads it from `FONTAWESOME_PACKAGE_TOKEN` or asks for it at a hidden prompt.
+- Get the catalog keys for the icons you need from UX; see [Choose Font Awesome Icons and Create a Manifest](CreateFontAwesomeManifest.md).
+- Install `@featherk/icons` and the application's Vite major (7 or 8) as development dependencies, as described in [Install the Vite Integration](FontAwesome.md#install-the-vite-integration).
+
+## Local Machine
+
+1. **Create `fontawesome.keys.json`** at the application root. It is the only list of selected icons: the setup command installs exactly what it lists, and the Vite plugin generates exactly what it lists. Pro keys go under `pro`.
+
+   ```json
+   {
+     "free": ["user"],
+     "pro": ["pro-house-light"]
+   }
+   ```
+
+2. **Install the source packages** from the application root. Enter the token at the hidden prompt when asked:
+
+   ```sh
+   npx featherk-fontawesome-setup --manifest fontawesome.keys.json
+   ```
+
+   The command looks up each key's exact package and version in the published catalog, then:
+   - installs the Free packages into the application's `devDependencies` from public npm, without the token;
+   - writes the Pro pins into `fontawesome-pro-sources/` (a `package.json`, a `.gitignore`, and an `.npmrc` with only a token placeholder), then installs that project with the token.
+
+   You never install a Font Awesome package by hand.
+
+3. **Commit** `fontawesome.keys.json`, `package.json`, `package-lock.json`, and `fontawesome-pro-sources/`, including its `package-lock.json`. Its `node_modules` stays ignored. Never put a real token in any `.npmrc`.
+
+4. **Add the plugin** to `vite.config.ts`:
+
+   ```ts
+   import { featherkFontAwesome } from "@featherk/icons/fontawesome/vite";
+
+   export default defineConfig({
+     plugins: [
+       vue(),
+       featherkFontAwesome({ manifest: "fontawesome.keys.json" }),
+     ],
+   });
+   ```
+
+5. **Run the application's normal scripts**, such as `npm run dev` and `npm run build`, without the token. Because `fontawesome-pro-sources/` is installed, they include the Pro icons. At the end of each build, Vite lists the source packages the icons came from; the list is informational only.
+
+6. **Render icons** from the virtual module; see [Render the Selected Key](FontAwesome.md#render-the-selected-key).
+
+   ```ts
+   import { getFaIcon } from "virtual:featherk/fontawesome";
+
+   const houseIcon = getFaIcon("pro-house-light");
+   ```
+
+If a type check such as `vue-tsc` runs before Vite, generate the declarations first with the same manifest:
+
+```sh
+npx featherk-fontawesome --manifest fontawesome.keys.json --virtual-types src/featherk-fontawesome.d.ts
+```
+
+### Fresh Clone
+
+After the application's normal `npm ci`, install the committed Pro sources from their lockfile with the token:
+
+```sh
+npx featherk-fontawesome-setup
+```
+
+Without this step, the application still installs and builds, with the Free icons only. Code that uses a Pro key then fails type checking, which shows that the step was skipped.
+
+### Changing Icons
+
+Edit `fontawesome.keys.json`, rerun `npx featherk-fontawesome-setup --manifest fontawesome.keys.json`, and commit the result. The command updates both sets of pins; when the Pro pins change, it regenerates `fontawesome-pro-sources/package-lock.json`. Restart Vite after installing.
+
+## CI
+
+A build that includes Pro icons has three steps. Only the middle one has the token:
+
+1. The application's normal `npm ci`, without the token.
+2. `npx featherk-fontawesome-setup`, with `FONTAWESOME_PACKAGE_TOKEN`. In CI it installs `fontawesome-pro-sources/` only from the committed lockfile and refuses `--manifest` setup.
+3. The application's normal build, test, and deploy steps, without the token.
+
+A build that skips step 2 is Free-only. Never expose the token to untrusted pull-request builds.
+
+### TeamCity
+
+1. Add a build parameter named `fontawesome.package.token` with type **Password**. Do not use an `env.` prefix; TeamCity would export it to every step.
+2. Leave the existing `npm ci` step unchanged, and add a Command Line step after it that sets the token for one command:
+
+   ```sh
+   # Linux agent
+   FONTAWESOME_PACKAGE_TOKEN='%fontawesome.package.token%' npx featherk-fontawesome-setup
+   ```
+
+   ```bat
+   rem Windows agent
+   set "FONTAWESOME_PACKAGE_TOKEN=%fontawesome.package.token%"
+   npx featherk-fontawesome-setup
+   ```
+
+3. Leave the build and the authorized deploy steps unchanged. They never reference the parameter.
+
+Build agents must be able to reach `npm.fontawesome.com`. For GitHub Actions and the full token-scoping rules, see [CI and Deployment](LICENSING.md#ci-and-deployment).
+
+### Build Caches
+
+A build cache keyed on tracked files, such as Turborepo's, must also key on whether `fontawesome-pro-sources/` is installed, or it can replay a Free build where Pro is expected. Add the install marker to the build's inputs:
+
+```json
+"inputs": ["$TURBO_DEFAULT$", "fontawesome-pro-sources/node_modules/.package-lock.json"]
+```
+
+Keep builds that include Pro icons out of shared or remote caches.
+
+## Distribution
+
+> [!WARNING]
+> A Pro build contains Font Awesome SVG path data. Publish it only where access controls, license coverage, and the required seats are confirmed, and preserve `featherk-fontawesome.licenses.txt` in every application distribution.
+
+## Checklist
+
+- [ ] License owner confirmed package access, release coverage, and seats
+- [ ] `fontawesome.keys.json` lists UX-provided keys, with Pro keys under `pro`
+- [ ] `npx featherk-fontawesome-setup --manifest fontawesome.keys.json` ran locally
+- [ ] `fontawesome-pro-sources/` and both lockfiles are committed; no token is in any file
+- [ ] `vite.config.ts` uses `featherkFontAwesome({ manifest: "fontawesome.keys.json" })`
+- [ ] CI runs `npx featherk-fontawesome-setup` with the token, between `npm ci` and the build
+- [ ] Any build cache keys on the `fontawesome-pro-sources` install marker
+- [ ] `featherk-fontawesome.licenses.txt` ships with the application