@featherk/icons 0.15.8 → 0.16.1

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` exception, 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

package/docs/fontawesome/LICENSING.md

@@ -20,15 +20,15 @@ The steps below are for Dev after UX/Design has selected the desired Pro variant
 
 1. Confirm entitlement, Creator coverage, and approved releases with the license owner.
 2. Dev obtains an authorized **Pro Package Token** from the Font Awesome account and supplies it privately as `FONTAWESOME_PACKAGE_TOKEN`.
-3. Dev installs the npm packages named by the manifest's `package` fields at their exact `version`s into the dedicated private project through its environment-referenced npm configuration.
-4. Dev enables the Pro profile and prepares declarations before type checking/building the application.
+3. Dev runs `featherk-fontawesome-setup --manifest fontawesome.keys.json`, which pins Free packages into the application and Pro packages into the private `fontawesome-pro-sources/` project at their exact catalog versions. See [Consuming Applications](#consuming-applications).
+4. Dev builds with the application's normal scripts; wherever `fontawesome-pro-sources/` is installed, the builds include the Pro icons.
 5. Dev preserves upstream notices and verifies publication/deployment boundaries before distribution.
 
 A package token is not a Kit code, account password, or Kendo license key. Never paste it into chat, screenshots, source files, command arguments, or logs. Follow the organization's approved token issuance/rotation process; do not share account passwords.
 
 ## This FeatherK Repository
 
-Normal root installation/build, Free demos, tests, and public package publishing require no Pro token. `demos/pro` is a separate private source project, not a root workspace. It requests exact `@fortawesome/pro-regular-svg-icons@7.0.0` and `@fortawesome/pro-light-svg-icons@7.0.0` packages; no paid dependency is added to the normal demo workspace or public icons package.
+Normal root installation/build, Free demos, tests, and public package publishing require no Pro token. `demos/fontawesome-pro-sources` is a separate private source project, not a root workspace; it is the same [default layout](#default-isolated-pro-sources) every consuming application uses. It requests exact `@fortawesome/pro-regular-svg-icons@7.0.0` and `@fortawesome/pro-light-svg-icons@7.0.0` packages; no paid dependency is added to the normal demo workspace or public icons package.
 
 The committed source-project npm configuration contains only a placeholder:
 
@@ -44,21 +44,21 @@ From the repository root, after confirming Steps 1-2:
 ```sh
 # The Font Awesome commands run from the built package; build it first.
 npm run build --workspace=@featherk/icons
-# Step 3: Authenticated installation runs only inside demos/pro.
+# Step 3: Authenticated installation runs only inside demos/fontawesome-pro-sources.
 npm run setup:fontawesome:pro --workspace=@featherk/demos
-# Step 4: Start the explicitly licensed local profile.
-npm run dev:pro --workspace=@featherk/demos
+# Step 4: Start the demo; with the sources installed, the Pro page renders.
+npm run dev --workspace=@featherk/demos
 # Step 5: Build the application and preserve emitted notices.
-npm run build:pro --workspace=@featherk/demos
+npm run build --workspace=@featherk/demos
 ```
 
-FeatherK's demos use the [isolated source project](#optional-pro-isolated-source-project) layout: `setup:fontawesome:pro` runs `featherk-fontawesome-setup --source-root pro`. The installer checks for the token without printing it. Initial installation creates an isolated lockfile; later runs use `npm ci` when it exists. Review and commit dependency/integrity metadata for reproducible CI, ensuring it contains no credentials. Source `node_modules` and application artifacts remain ignored. No paid installation has been performed as part of implementing this setup.
+`setup:fontawesome:pro` runs `featherk-fontawesome-setup` without arguments, which installs `demos/fontawesome-pro-sources` from its committed lockfile with `npm ci`. The installer checks for the token without printing it. Review and commit dependency/integrity metadata for reproducible CI, ensuring it contains no credentials. Source `node_modules` and application artifacts remain ignored.
 
-The UX-approved Pro manifest requests Regular Rocket, Light Feather, and Light Heart. These pins are requested examples, not verified downloads. If entitlement, releases, or exports are unavailable, Dev must stop installation/generation and return to UX/Design for approval before changing the manifest or dependencies; never substitute silently.
+The UX-approved Pro manifest requests Regular Rocket, Light Feather, Light Heart, and Light House (`pro-rocket-regular`, `pro-feather-light`, `pro-heart-light`, `pro-house-light`). An authorized installation of these pins succeeded on October 15, 2026 (see [Validation Boundary](#validation-boundary)). If entitlement, releases, or exports later become unavailable, Dev must stop installation/generation and return to UX/Design for approval before changing the manifest or dependencies; never substitute silently.
 
-The profile wrappers enable the non-secret `FEATHERK_FONTAWESOME_PRO=1` build flag and remove the package token from child build environments. They invoke the demo's own commands, not the root Turborepo cached build. Do not put paid outputs into shared/untrusted caches.
+The demo has no separate Pro scripts: its normal `dev` and `build` include the Pro icons once `demos/fontawesome-pro-sources` is installed, and only the Free icons otherwise. `demos/turbo.json` adds `fontawesome-pro-sources/node_modules/.package-lock.json`, which npm writes on install, to the build's cache inputs, so the root Turborepo build never replays a Free build where Pro sources are installed, or the reverse. Do not put paid outputs into shared or remote caches.
 
-`sourceRoot: "pro"` resolves installed licensed packages while output guards remain relative to the demo project. Node resolution also finds already installed Free packages in parent workspace directories. The next normal preparation restores the Free-only generated key union.
+The demo's plugin options are `{ manifest: "fontawesome.keys.json" }`. With the sources installed, the plugin resolves licensed packages from `fontawesome-pro-sources/` while output guards remain relative to the demo project; Node resolution also finds already installed Free packages in parent workspace directories. Without them, it does not read that directory.
 
 Routes are `/icons/fontawesome/free` and `/icons/fontawesome/pro`; `/icons/fontawesome` redirects to Free. The Pro page shows an unavailable state without a licensed profile, never fabricated artwork. Enabling the profile with missing/invalid sources fails the build rather than hiding an error.
 
@@ -77,7 +77,7 @@ setup_status=$?
 unset fa_token
 # Step 4: Start only after successful installation.
 if [[ $setup_status -eq 0 ]]; then
-  npm run dev:pro --workspace=@featherk/demos
+  npm run dev --workspace=@featherk/demos
 fi
 ```
 
@@ -96,7 +96,7 @@ try {
   Remove-Item Env:FONTAWESOME_PACKAGE_TOKEN -ErrorAction SilentlyContinue
 }
 # Step 4: Start only after successful installation.
-npm run dev:pro --workspace=@featherk/demos
+npm run dev --workspace=@featherk/demos
 ```
 
 Do not continue after an install error. `401`/`403` can indicate invalid/revoked credentials or insufficient entitlement. Inspect status codes without printing token/config contents. Missing releases/exports need a source/approval review, not an unpinned upgrade.
@@ -105,11 +105,11 @@ Do not continue after an install error. `401`/`403` can indicate invalid/revoked
 
 Consumers need their own covered access or an enterprise agreement that actually covers them. The public FeatherK package grants no Pro rights.
 
-`@featherk/icons` provides `featherk-fontawesome-setup` for consumer setup. Run it through `npx` or an npm script from the application root, once per application, on a developer machine. It reads the UX-provided keys-only manifest (or `--keys a,b`) and pins each package to the exact catalog version. The manifest is the same file the Vite plugin and CLI use: a `free` array of catalog keys plus an optional `pro` array.
+`@featherk/icons` provides `featherk-fontawesome-setup` for consumer setup. Run it through `npx` or an npm script from the application root, on a developer machine. It reads the UX-provided keys-only manifest, the same file the Vite plugin and CLI use (a `free` array of catalog keys plus an optional `pro` array), and pins each package to the exact catalog version.
 
-### Standard: Free and Pro Together
+### Default: Isolated Pro Sources
 
-Most applications use both tiers, so the standard setup installs Free and Pro packages together as ordinary `devDependencies`:
+Every application uses this layout unless it has a specific reason not to:
 
 ```sh
 npx featherk-fontawesome-setup --manifest fontawesome.keys.json
@@ -117,63 +117,54 @@ npx featherk-fontawesome-setup --manifest fontawesome.keys.json
 
 The command:
 
-1. Adds these lines to the application's `.npmrc`, creating it if needed. Existing settings are kept, and the lines are not duplicated on later runs:
+1. Installs the exact Free pins into the application's `devDependencies` from public npm. This step needs no token.
+2. Writes the exact Pro pins into `fontawesome-pro-sources/`, a private source project next to the application's `package.json`, then installs it with the token from `FONTAWESOME_PACKAGE_TOKEN` or a hidden prompt. The project contains a `package.json`, a `.gitignore` for its `node_modules`, and an `.npmrc` with only the token placeholder:
 
    ```ini
    @fortawesome:registry=https://npm.fontawesome.com/
    //npm.fontawesome.com/:_authToken=${FONTAWESOME_PACKAGE_TOKEN}
    ```
 
-2. Installs the exact Free and Pro pins with `npm install --save-dev --save-exact`, using the token from `FONTAWESOME_PACKAGE_TOKEN` or a hidden prompt.
+Commit `package.json`, `package-lock.json`, and `fontawesome-pro-sources/`, including its `package-lock.json`. Configure the Vite plugin with `featherkFontAwesome({ manifest: "fontawesome.keys.json" })`.
 
-Commit `.npmrc`, `package.json`, and `package-lock.json`. Then configure the Vite plugin with `allowPro: true` and the manifest's Free and Pro keys, without `sourceRoot` or separate Pro scripts.
+The directory name `fontawesome-pro-sources` is fixed, so every team's setup looks the same. The plugin and CLI find the directory themselves, and installing it is what turns Pro icons on. The application's normal `dev` and `build` scripts need no changes:
 
-The scope line routes **all** `@fortawesome` packages, Free included, to the Font Awesome registry. Every install therefore needs `FONTAWESOME_PACKAGE_TOKEN`, and everyone who installs the application needs an applicable seat.
+- **Where `fontawesome-pro-sources/` is installed** (its `node_modules` exists), builds generate the `free` and `pro` keys, resolving Pro packages from it.
+- **Where it is not installed**, builds generate the `free` keys alone and never read it. If a job should have installed it and didn't, code that uses a Pro key fails type checking, because the generated key union then contains only Free keys.
 
-#### Token-Scoped Installs
+The application's own `npm ci` never needs the token, so developers and CI jobs without Pro access can still install it and build Free-only. Only installing `fontawesome-pro-sources/` needs Pro access, and everyone who does, or who builds where it is installed, needs an applicable seat.
 
-`npm ci` runs lifecycle scripts from the application and every dependency, and later build tools run arbitrary Node code. Any of them can read a token in their environment. Log masking and Vite's `VITE_` client-variable filter do not prevent this. Do not export the token persistently or for a whole CI build. Give it only to an install that skips scripts, then run anything that needs scripts without it:
+A build cache keyed on tracked files, such as Turborepo's, must also key on whether the sources are installed, or it can replay a Free build where Pro is expected. Add the install marker that npm writes to the build's inputs, for example in Turborepo:
 
-1. With the token: `npm ci --ignore-scripts`.
-2. Without the token, run any install scripts the application needs:
-   - `npm rebuild` runs the dependency install scripts that step 1 skipped. On npm 12 and later, dependency scripts run only when approved in the application's `allowScripts` (`npm install-scripts approve <pkg>`), and `npm rebuild` follows the same approvals. Older npm versions run all of them.
-   - `npm rebuild` does not run the application's own lifecycle scripts. Run those explicitly, for example `npm run prepare --if-present`.
-3. Without the token: `npm run dev`, `npm run build`, tests, and deployment. npm runs normally when the `.npmrc` placeholder is unset; only `@fortawesome` registry requests need it.
+```json
+"inputs": ["$TURBO_DEFAULT$", "fontawesome-pro-sources/node_modules/.package-lock.json"]
+```
 
-Git Bash:
+Keep builds that include Pro icons out of shared or remote caches.
 
-```bash
-read -r -s -p "Font Awesome package token: " fa_token; echo
-FONTAWESOME_PACKAGE_TOKEN="$fa_token" npm ci --ignore-scripts
-install_status=$?
-unset fa_token
-[[ $install_status -eq 0 ]] && npm rebuild
-```
+After changing the manifest, rerun the same command. It updates both sets of pins; when the Pro pins change, it removes the stale `fontawesome-pro-sources/package-lock.json` and the install regenerates it. Review and commit the result.
 
-PowerShell:
+On a fresh clone and in CI, run the application's normal `npm ci`, then install the source project from its committed lockfile:
 
-```powershell
-$env:FONTAWESOME_PACKAGE_TOKEN = [System.Net.NetworkCredential]::new(
-  "", (Read-Host "Font Awesome package token" -AsSecureString)
-).Password
-try {
-  npm ci --ignore-scripts
-  if ($LASTEXITCODE -ne 0) { throw "Font Awesome package installation failed." }
-} finally {
-  Remove-Item Env:FONTAWESOME_PACKAGE_TOKEN -ErrorAction SilentlyContinue
-}
-npm rebuild
+```sh
+npx featherk-fontawesome-setup
 ```
 
-The setup command follows the same rule. It installs with `--ignore-scripts` and passes the token only to that npm process. For CI, see [TeamCity](#teamcity).
+Without arguments, the command runs `npm ci` in `fontawesome-pro-sources/` with the token, skipping lifecycle scripts and ignoring npm workspace settings. In CI it requires the committed lockfile. See [CI and Deployment](#ci-and-deployment).
 
-Before supplying the token, the command checks `.npmrc`. It refuses any of the following:
+### Setup Safety Checks
+
+Before supplying the token, the command checks `fontawesome-pro-sources/.npmrc`. It refuses any of the following:
 
 - a `@fortawesome` registry other than `https://npm.fontawesome.com/`
 - any reference to `FONTAWESOME_PACKAGE_TOKEN` outside `//npm.fontawesome.com/:_authToken`
 - any other `npm.fontawesome.com` credential, including a literal token
 
-It also pins the Font Awesome registry on the npm command line, which overrides other npm configuration. The token therefore can only be sent to Font Awesome. The command refuses to run in CI, because it changes `package.json`. It installs with `--ignore-scripts`, so lifecycle scripts never run while the token is present, and it never prints the token. The isolated source-project install applies the same checks, and also requires both Font Awesome lines.
+It also pins the Font Awesome registry on the npm command line, which overrides other npm configuration, so the token can only be sent to Font Awesome. It installs with `--ignore-scripts`, so lifecycle scripts never run while the token is present, passes the token only to that npm process, and never prints it. Setup with `--manifest` changes `package.json`, so it refuses to run in CI.
+
+`npm ci` lifecycle scripts and build tools run arbitrary Node code that can read any token in their environment, and log masking does not prevent that. Give the token only to `featherk-fontawesome-setup`, never to the application's `npm ci`, its build, or a whole CI job, and do not export it persistently.
+
+The application's own `.npmrc` must not route `@fortawesome` to a registry: Free packages come from public npm, and Pro packages only from `fontawesome-pro-sources/`. Setup refuses an application whose `.npmrc` does. That includes an application set up with the `--pro-in-app` option, which shipped in 0.16.0 and was then removed; remove the Font Awesome lines from its `.npmrc` and any `@fortawesome/pro-*` packages from its `devDependencies`, then rerun setup with `--manifest`.
 
 ### Exception: Free Only
 
@@ -183,31 +174,20 @@ For an application that will use only Free icons:
 npx featherk-fontawesome-setup --manifest fontawesome.keys.json --free-only
 ```
 
-Free packages come from public npm. The command writes no `.npmrc` lines and needs no token or CI configuration. It fails if the manifest contains Pro keys, or if `.npmrc` already routes `@fortawesome` to a registry. Leave `allowPro` unset.
+Free packages come from public npm. The command needs no token or CI configuration and creates no source project. The default command behaves the same way for a manifest without Pro keys; `--free-only` also guarantees it, failing if the manifest contains Pro keys, if `fontawesome-pro-sources/` exists, or if `.npmrc` routes `@fortawesome` to a registry. Configure the Vite plugin with `{ manifest: "fontawesome.keys.json" }`. To add Pro later, add the keys to the manifest and rerun without `--free-only`.
 
-Free-only is a per-application choice, not a per-developer one. In a Free and Pro application, the lockfile resolves Free packages through the Font Awesome registry, so a developer without the token cannot install that application. To move a Free-only application to Pro later, add the Pro keys to the manifest and rerun the command without `--free-only`, then add the CI token parameter.
+### Generation and Licensing Boundaries
 
-### Optional Pro: Isolated Source Project
+Keep Pro keys in the manifest's `pro` group. Public or uncredentialed builds must not include paid inputs: run them where `fontawesome-pro-sources/` is not installed.
 
-Some projects must keep Pro optional so normal installs never need a token. FeatherK's own demos work this way. They install Pro packages into a separate private project and pass `sourceRoot` to the Vite plugin only in an authorized profile, for example `featherkFontAwesome({ keys, allowPro: true, sourceRoot: "pro" })`. The same command supports this layout:
-
-```sh
-# Scaffold .npmrc (token placeholder only), package.json with exact Pro pins, and .gitignore.
-npx featherk-fontawesome-setup --source-root fontawesome-pro-sources --init --manifest fontawesome.keys.json
-# Install with the token; this creates fontawesome-pro-sources/package-lock.json.
-npx featherk-fontawesome-setup --source-root fontawesome-pro-sources
-```
-
-Commit the scaffolded files and the lockfile. `--init` pins only Pro keys, because Free packages belong in the application's own `devDependencies`. It refuses to overwrite existing files unless you pass `--force`, and it needs no token. When `--init --force` changes the dependencies, for example by adding a Pro package, it removes the now-stale `package-lock.json`. The next install then regenerates it with `npm install`; review and commit the new lockfile. After editing the source project's `package.json` by hand, run the install with `--refresh-lock` to update the lockfile. Later runs use `npm ci` in the source project and remove npm workspace settings, so `--workspace` invocations target only that project. In CI, `--init` and `--refresh-lock` are refused and the lockfile is required. The application's own `npm ci` needs no token. CI adds a separate token-scoped install step for the source project before the Pro build.
-
-Keep Pro keys in the manifest's `pro` group and include them only in the authorized profile. Optional profiles must not silently include paid inputs in public/uncredentialed builds. The `dev:pro`/`build:pro` profile scripts above are repository demo helpers.
-
-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. The `allowPro` option prevents accidental selection; it does not verify license entitlement. 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 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. Listing a key under `pro`, and installing `fontawesome-pro-sources/` only where Pro is wanted, prevent accidental selection; they do not verify license entitlement. 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
 
 FeatherK and `feather-k-<demo-name>` repositories use GitHub Actions. TeamCity applies only to enterprise apps using that platform.
 
+A build that includes Pro icons has three steps: the application's normal `npm ci` without the token, a token-scoped `npx featherk-fontawesome-setup` that installs `fontawesome-pro-sources/` from its lockfile, and the application's normal build without the token. Builds that don't need Pro icons skip the middle step and come out Free-only.
+
 Use a dedicated trusted Actions job with a protected Environment and approval/branch rules. Supply the token only to source installation, not public publishing or client compilation. After checkout and Node/root dependency setup:
 
 ```yaml
@@ -217,39 +197,38 @@ Use a dedicated trusted Actions job with a protected Environment and approval/br
     NPM_CONFIG_CACHE: ${{ runner.temp }}/fontawesome-pro-cache
   run: npm run setup:fontawesome:pro --workspace=@featherk/demos
 - name: Build licensed demo application
-  run: npm run build:pro --workspace=@featherk/demos
+  run: npm run build --workspace=@featherk/demos
 ```
 
-In CI, detected from `CI`, `TEAMCITY_VERSION`, or `GITHUB_ACTIONS`, the setup command refuses app-root setup and `--init`, and an isolated install requires the committed `package-lock.json`. Unattended jobs therefore only run a locked `npm ci` and never resolve new versions. In every layout, supply the token only to the install step that skips lifecycle scripts, never to the whole job. See [Token-Scoped Installs](#token-scoped-installs). With no token and no interactive terminal, the command fails instead of prompting.
+In CI, detected from `CI`, `TEAMCITY_VERSION`, or `GITHUB_ACTIONS`, the setup command refuses `--manifest` setup, and the source-project install requires the committed `package-lock.json`. Unattended jobs therefore only run a locked `npm ci` and never resolve new versions. Supply the token only to the `featherk-fontawesome-setup` step, never to the whole job. With no token and no interactive terminal, the command fails instead of prompting.
 
 Configure the protected Environment separately; this fragment grants no license rights. Restrict paid caches/archives/artifacts, and never execute untrusted PR code with the token, including via `pull_request_target`. Normal public FeatherK publishing must not receive Pro credentials or use the licensed profile.
 
 ### TeamCity
 
-Do not define the token as an `env.` parameter. TeamCity passes `env.` parameters to every step in the build, so build tools and lifecycle scripts could read the token. Instead, scope it to the install step:
+Do not define the token as an `env.` parameter. TeamCity passes `env.` parameters to every step in the build, so build tools and lifecycle scripts could read the token. Instead, scope it to one install step:
 
 1. In the build configuration, add a parameter named `fontawesome.package.token` with type **Password**. Use no `env.` prefix, so TeamCity does not export it to the steps' environment.
-2. Change the existing install step to a Command Line step that sets the variable for the install command only. Each Command Line step runs in its own process, so the variable does not carry into later steps.
+2. Add a Command Line step that sets the variable for one command only. Each Command Line step runs in its own process, so the variable does not carry into later steps.
 
-   Linux agent:
+   Leave the application's existing `npm ci` step unchanged and add this step after it:
 
    ```sh
-   FONTAWESOME_PACKAGE_TOKEN='%fontawesome.package.token%' npm ci --ignore-scripts
+   # Linux agent
+   FONTAWESOME_PACKAGE_TOKEN='%fontawesome.package.token%' npx featherk-fontawesome-setup
    ```
 
-   Windows agent:
-
    ```bat
+   rem Windows agent
    set "FONTAWESOME_PACKAGE_TOKEN=%fontawesome.package.token%"
-   npm ci --ignore-scripts
+   npx featherk-fontawesome-setup
    ```
 
-3. If the application or its dependencies need install scripts, add a step without the token. Use `npm rebuild` for dependency scripts, which follows `allowScripts` approvals on npm 12 and later. Run the application's own scripts explicitly, for example `npm run prepare --if-present`, because `npm rebuild` does not run them. See [Token-Scoped Installs](#token-scoped-installs).
-4. Leave the build, test, and deploy steps unchanged. They never reference the parameter.
+   Leave the build step unchanged: with the sources installed, the normal build includes the Pro icons.
 
-Password parameters are masked in build logs, but masking does not stop code running in a step from reading the value. TeamCity also writes the step script, with the substituted value, to a temporary file on the agent. Limit the parameter to trusted build configurations and agents, and never run untrusted pull-request code in a build that defines it. Build agents must be able to reach `npm.fontawesome.com`.
+3. Leave the build, test, and deploy steps free of the parameter. They never reference it.
 
-This applies to the [standard Free and Pro setup](#standard-free-and-pro-together). For the [isolated source project](#optional-pro-isolated-source-project), the app's normal install needs no token. Add a separate token-scoped step that runs the source install script, for example `npm run fontawesome:install:pro`, before the Pro build. [Free-only](#exception-free-only) applications need no TeamCity configuration.
+Password parameters are masked in build logs, but masking does not stop code running in a step from reading the value. TeamCity also writes the step script, with the substituted value, to a temporary file on the agent. Limit the parameter to trusted build configurations and agents, and never run untrusted pull-request code in a build that defines it. Build agents must be able to reach `npm.fontawesome.com`. [Free-only](#exception-free-only) applications need no TeamCity configuration.
 
 Tokens do not expand Creator seats.
 
@@ -259,6 +238,6 @@ Enterprise Pages must enforce authentication on deployed URLs/static assets; rep
 
 Public `@featherk/icons` artifacts contain tooling and owned icons only: no paid dependencies/artwork, source caches, credentials, or generated paid-icon collections. Private distribution alone does not establish entitlement.
 
-Isolated-source resolution uses synthetic tests. Free generation and Pro-unavailable UI can be checked without secrets. Real paid exports, license notices, and enabled Pro rendering remain unverified until an authorized installation succeeds. Pro+ collections requiring Kits remain outside this no-Kit implementation.
+Automated tests use synthetic packages, so public CI needs no secrets. On October 15, 2026, an authorized installation of `demos/fontawesome-pro-sources` was checked locally: `npm run verify:fontawesome --workspace=@featherk/demos` verified all 14 demo selections, including the four Pro exports, against the installed packages (path data, viewBox, version, and style), and the build emitted both the Free and Pro license notices. Rendering of the Pro page in a browser was not part of that check. Re-run the verification after changing pins. Pro+ collections requiring Kits remain outside this no-Kit implementation.
 
-References: [package authentication](https://docs.fontawesome.com/web/setup/packages), [Pro license](https://fontawesome.com/license), and [Font Awesome account](https://fontawesome.com/account).
+References: [package authentication](https://docs.fontawesome.com/web/setup/packages), [Pro license](https://fontawesome.com/license), and [Font Awesome account](https://fontawesome.com/account).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/icons",
-  "version": "0.15.8",
+  "version": "0.16.1",
   "main": "dist/featherk-icons.umd.js",
   "module": "dist/featherk-icons.es.js",
   "types": "dist/index.d.ts",

package/dist/fontawesome/chunks/manifest-BB3q10t1.mjs

@@ -1,20 +0,0 @@
-import { readFile } from "node:fs/promises";
-const isKeyList = (value) => Array.isArray(value) && value.every((key) => typeof key === "string");
-function parseFontAwesomeManifest(manifest) {
-  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
-    throw new Error("Font Awesome manifest must be a JSON object");
-  }
-  const { free, pro } = manifest;
-  if (!isKeyList(free) || pro !== void 0 && !isKeyList(pro)) {
-    throw new Error(
-      'Font Awesome manifest must contain "free" and optional "pro" key arrays'
-    );
-  }
-  return { free, pro: pro ?? [] };
-}
-async function readFontAwesomeManifest(path) {
-  return parseFontAwesomeManifest(JSON.parse(await readFile(path, "utf8")));
-}
-export {
-  readFontAwesomeManifest as r
-};

package/dist/fontawesome/chunks/manifest-C15Xa22L.cjs

@@ -1,19 +0,0 @@
-"use strict";
-const promises = require("node:fs/promises");
-const isKeyList = (value) => Array.isArray(value) && value.every((key) => typeof key === "string");
-function parseFontAwesomeManifest(manifest) {
-  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
-    throw new Error("Font Awesome manifest must be a JSON object");
-  }
-  const { free, pro } = manifest;
-  if (!isKeyList(free) || pro !== void 0 && !isKeyList(pro)) {
-    throw new Error(
-      'Font Awesome manifest must contain "free" and optional "pro" key arrays'
-    );
-  }
-  return { free, pro: pro ?? [] };
-}
-async function readFontAwesomeManifest(path) {
-  return parseFontAwesomeManifest(JSON.parse(await promises.readFile(path, "utf8")));
-}
-exports.readFontAwesomeManifest = readFontAwesomeManifest;