Add kit subset awareness

plugins/icons/skills/add-icon/SKILL.md

@@ -22,17 +22,31 @@ Scripts referenced from `suggest-icon` are relative to `plugins/icons/skills/sug
 
 At the start, run `command -v fa` to check whether the `fa` CLI is available on PATH.
 
-- **If `fa` is found:** use it for icon lookups and kit fetching (it returns structured JSON). For kit operations (`fa kits`), check auth first: run `fa whoami` to see if the user is logged in. If logged in, `fa kits` will work directly. If not logged in but `FA_API_TOKEN` is set, `fa kits` will also work. If neither, tell the user: "You need to be logged in to the Font Awesome CLI for kit operations. Run `fa login` in a separate terminal, then come back here and try again." If they cannot log in, fall back to `fetch-kit.py`.
+The `fa kit` subcommand requires `fa` version 0.8.0 or newer. If the `fa kit` subcommand is needed, recommend the user upgrade `fa`, using instructions here: https://docs.fontawesome.com/web/use-with/fa-cli
+
+- **If `fa` is found:** use it for icon lookups and kit fetching (it returns structured JSON). For kit operations (`fa kits` and `fa kit`), check auth first: run `fa whoami` to see if the user is logged in. If logged in, these will work directly. If not logged in but `FA_API_TOKEN` is set, they will also work. If neither, tell the user: "You need to be logged in to the Font Awesome CLI for kit operations. Run `fa login` in a separate terminal, then come back here and try again." If they cannot log in, fall back to `fetch-kit.py`. When the project uses a Kit, `fa kit icon --kit-token <TOKEN> <icon>` tells you whether a specific icon is in the Kit's subset and which family styles it's available in — use it to avoid adding an icon the Kit doesn't include (see step 3).
 - **If `fa` is not found:** fall back to the Python scripts described below.
-- **`latest-version.py`** is always used for version detection — the `fa` CLI has no equivalent.
+- Use `latest-version.py` to get the latest version.
 
 ## Steps
 
 ### 1. Resolve the icon name
 
-First, determine the Font Awesome version. If the user specifies one, use that. Otherwise run `./scripts/latest-version.py` (in the `suggest-icon` skill directory) to get the latest.
+First, determine whether the project uses a Kit for integrating Font Awesome. If the project has a `.font-awesome.md` file, read it to determine whether a Kit is in use.
+
+#### If project uses a Kit
+
+If the project uses a Kit, then verify that the icon exists in the particular Kit's subset. This can only be done with the `fa` CLI. If the user is not logged in, prompt them to run `fa login` in a separate terminal first.
+
+To verify the icon exists in the kit, run `fa kit icon --kit-token <TOKEN> <icon>`.
 
-Then verify the icon exists:
+If the icon does not exist, invoke the `/suggest-icon` skill internally with the user's `icon` argument as the use-case. Auto-accept the top recommendation without prompting the user to confirm, if there are any recommendations.
+
+If `/suggest-icon` offers no recommendations, it may be because the Kit's subset does not include any icons similar to the user's query. In that case, search all of Font Awesome (not just the Kit) for similar icons using `fa search --version <version> --query <icon>`. Let the user know that the icon they requested is not in their Kit's subset, but they could add it to their Kit at https://fontawesome.com/kits.
+
+#### If project does not use a Kit
+
+If the project does not use a Kit, then to verify the icon exists:
 
 - **`fa` CLI:** Run `fa icons --version <version> --name <icon>`. The icon exists if `data.release.icon` is non-null. The `familyStylesByLicense` field shows the free/pro breakdown.
 - **Fallback:** Run `./scripts/icon-exists.py --version <version> --icon-name <icon>`. Exit code `0` means the icon exists; exit code `1` means it does not.
@@ -78,7 +92,7 @@ The subagent should return: which Font Awesome packages are installed (with vers
 
 After the subagent returns, if a kit ID was found, fetch the kit details:
 
-- **`fa` CLI:** Run `fa kits --kit-token <id>`. Returns JSON with the kit's version, license, technology, and available families. Requires the user to be logged in (`fa whoami` returns success) or `FA_API_TOKEN` to be set. If neither, prompt the user to run `fa login` in a separate terminal first.
+- **`fa` CLI:** Run `fa kit show --kit-token <id>`. Returns JSON with the kit's version, license, technology, and available families. Requires the user to be logged in (`fa whoami` returns success) or `FA_API_TOKEN` to be set. If neither, prompt the user to run `fa login` in a separate terminal first.
 - **Fallback:** Run `./scripts/fetch-kit.py --kit-id <id>` (in the `add-icon` skill directory) to get the kit's version, license, method, and available families.
 
 After discovery, determine:
@@ -113,7 +127,23 @@ Tell the user: "I've written `.font-awesome.md` with your project's Font Awesome
 2. Otherwise, use the default family from `.font-awesome.md`.
 3. If neither, default to `classic`.
 
-Verify the icon is available in the chosen style and family by checking the output from `icon-exists.py` (it prints available families and styles). If the icon is not available in the requested style or family, tell the user and suggest available alternatives. Also check that the chosen family is in the project's available families list — if not, warn the user.
+If `.font-awesome.md` records a **Kit ID** (kit token), the project's icons come from a Kit, and a Kit contains only a subset of all Font Awesome icons. **Do not add an icon the Kit does not include** — it will not render.
+
+Verify the icon is available in the chosen style and family, based on whether the project uses a Kit:
+
+#### If the project uses a Kit
+
+Re-use the output of `fa kit icon --kit-token <TOKEN> <icon>` from Step 1: "Resolve the icon name". There it was used to resolve the icon name. The same output can be used here to check whether the icon is available in the chosen family-style.
+
+If your chosen family-style for the icon isn't included but another is, tell the user, and ask if they'd prefer to use another family-style that is available, or else tell them to add the missing one to the kit's subset.
+
+If the icon is **not** in the Kit at all, stop before generating code. Tell the user the icon isn't part of their Kit's subset, and offer two paths: (a) add the icon to the Kit at https://fontawesome.com/kits and re-run, or (b) pick a kit-available alternative — you can run `/suggest-icon` (which is Kit-aware) to find one. Do not silently add an icon the Kit lacks.
+
+To list what the Kit does contain, `fa kit family-styles --kit-token <TOKEN>` shows the available family-styles and `fa kit icons --kit-token <TOKEN>` lists the available icon variants, which are the icons in specific family-styles. Both are paginated queries.
+
+#### If the project does not use a Kit
+
+Run `icon-exists.py`. Its output shows available families and styles. If the icon is not available in the requested style or family, tell the user and suggest available alternatives. Also check that the chosen family is in the project's available families list — if not, warn the user.
 
 ### 4. Generate the code
 

plugins/icons/skills/add-icon/font-awesome-md-format.md

@@ -14,7 +14,8 @@ Detected by the Font Awesome agent tools. Commit this file so the whole team ben
 - **Method:** [e.g., React components via @fortawesome/react-fontawesome, Kit embed (SVG+JS), CDN, self-hosted web fonts]
 - **Version:** [e.g., 7.2.0]
 - **License:** [Free or Pro]
-- **Kit ID:** [if applicable, or omit]
+- **Kit ID:** [if applicable, or omit — this is the Kit token, e.g. `abc123def4`. It's usable as `--kit-token` with the `fa` CLI: `fa kit icon/icons/family-styles ...` to check what the Kit's subset includes, and `fa search --kit-token <TOKEN>` to search only kit-available icons. `/add-icon` and `/suggest-icon` use it to avoid adding or suggesting icons the Kit doesn't contain.]
+- **Kit Revision:** [e.g. 42 -- this is the Kit's revision number, useful for tracking updates. It changes every time a kit is updated, whether by changing its subset, settings, or adding/removing/changing any custom icons. Its found as `kitRevision` in the kit detail from `fa kit show --kit-token <TOKEN>`]
 - **CDN URL:** [if applicable, or omit]
 - **Families:** [e.g., classic, duotone, sharp, sharp-duotone — list all available families]
 
@@ -45,4 +46,4 @@ Detected by the Font Awesome agent tools. Commit this file so the whole team ben
 
 ## When to update
 
-After any skill run, review whether new information was discovered that is missing from the file — a new import pattern, a family not listed, a wrapper component not documented, a version change, etc. Update only the sections that are incomplete or outdated. Do not rewrite sections that are already accurate.
+After any skill run, review whether new information was discovered that is missing from the file — a new import pattern, a family not listed, a wrapper component not documented, a version change, a kitRevision change, etc. Update only the sections that are incomplete or outdated. Do not rewrite sections that are already accurate.

plugins/icons/skills/setup-fa/SKILL.md

@@ -27,9 +27,11 @@ Before starting, check whether `.font-awesome.md` already exists in the project
 
 Run `command -v fa` to check whether the `fa` CLI is available on PATH.
 
-- **If `fa` is found:** use it for Kit operations and version queries (it returns structured JSON). For kit operations (`fa kits`), check auth first: run `fa whoami` to see if the user is logged in. If logged in, `fa kits` will work directly. If not logged in but `FA_API_TOKEN` is set, `fa kits` will also work. If neither, tell the user: "You need to be logged in to the Font Awesome CLI for kit operations. Run `fa login` in a separate terminal, then come back here and try again."
+The `fa kit` subcommand requires `fa` version 0.8.0 or newer. If the `fa kit` subcommand is needed, recommend the user upgrade `fa`, using instructions here: https://docs.fontawesome.com/web/use-with/fa-cli
+
+- **If `fa` is found:** use it for Kit operations and version queries (it returns structured JSON). For kit operations (`fa kits` and `fa kit`), check auth first: run `fa whoami` to see if the user is logged in. If logged in, `fa kits` will work directly. If not logged in but `FA_API_TOKEN` is set, `fa kits` will also work. If neither, tell the user: "You need to be logged in to the Font Awesome CLI for kit operations. Run `fa login` in a separate terminal, then come back here and try again."
 - **If `fa` is not found:** fall back to the Python scripts described below where applicable.
-- **`latest-version.py`** (in the `suggest-icon` skill directory) is always used for version detection.
+- Use `latest-version.py` to get the latest version.
 
 ## Steps
 
@@ -47,12 +49,13 @@ Run `command -v fa` to check whether the `fa` CLI is available on PATH.
   - `wp-content/`, `functions.php`, `style.css` with WordPress theme headers → WordPress
   - `.html` files with no framework → static HTML
 - **Existing Font Awesome traces** — check if Font Awesome is partially installed (old version, broken setup, etc.). Look for `@fortawesome` packages in `package.json`, Kit script tags in HTML, CDN links, or Font Awesome CSS/font files.
+- **Icons already in use** — collect the set of Font Awesome icons the project already references, with the family and style for each where determinable. Look in class-based markup (`fa-solid fa-cart-shopping`, `fa-sharp fa-regular fa-user`), React/Vue imports (`faCartShopping` → `cart-shopping`), `<FontAwesomeIcon icon={...}>` / `icon={['far', 'cart-shopping']}` usages, sprite `<use href="...#icon-name">`, and `<fa-icon>` elements. This list drives the Kit-coverage check in step 4 — capture canonical icon names (kebab-case) and note the family-style when you can infer it.
 - **License clues** — `fontawesome-pro` packages, Pro CDN URLs, or Kit config indicating Pro.
 - **Project structure** — where HTML templates live, where CSS/JS entry points are, where components are defined.
 
 If the user passed a `framework` argument, use that instead of auto-detecting.
 
-The subagent should return a structured summary of what it found.
+The subagent should return a structured summary of what it found, including the list of icons already in use (with family-style where known).
 
 ### 2. Recommend an integration method
 
@@ -71,6 +74,8 @@ Has a Font Awesome account/Kit?
 
 Always recommend creating a Font Awesome account and using a Kit — even for free-tier users. Kits provide the best experience (auto-subsetting, easy updates, custom icons) and a free account is all that's needed. Do not recommend third-party CDNs or other unofficial distribution methods.
 
+**If the project already uses icons (from step 1), the chosen Kit should include them.** A Kit contains only a subset of all Font Awesome icons, so a Kit that omits icons the project already relies on will leave those icons broken. If the user has more than one Kit, guide them toward one whose subset and family styles cover the icons already in use. If they're creating a new Kit, mention that it needs to include those icons (and the families-styles they use). You'll verify the actual coverage once you have the Kit token, in step 4.
+
 Present the recommendation to the user with a brief explanation of why. **Wait for the user to confirm before proceeding** — setup involves installing packages or modifying project files.
 
 ### 3. Fetch documentation for the chosen method
@@ -94,6 +99,20 @@ Follow the path that matches the chosen method. Each path is documented in a sep
 
 After completing the path-specific steps, if the method involved installing npm packages (Paths B, D), read `references/path-f-framework-init.md` for framework-specific initialization code.
 
+#### Verify the Kit covers the icons already in use
+
+Once you have the Kit token (any Kit path: A, B, or C), and the project already used Font Awesome icons (collected in step 1), confirm the Kit's subset actually includes them. This requires the `fa` CLI and an authenticated session (`fa whoami`, or `FA_API_TOKEN` set).
+
+1. Check each icon already in use with `fa kit icon --kit-token <TOKEN> <icon>`. This reports whether the icon is in the Kit and which family-styles it covers. For a small number of icons, check them individually; for many, you can list the Kit's contents with `fa kit icons --kit-token <TOKEN>` (paginated) and compare locally.
+2. Confirm the families-styles the project uses are present with `fa kit family-styles --kit-token <TOKEN>` (paginated), or `fa kit family-style --kit-token <TOKEN> ...` to look up a single one.
+3. If any in-use icon (or its family style) is **missing** from the Kit, warn the user explicitly. List exactly which icons are not covered and in which family styles, for example:
+
+   > Your project uses `fa-thin fa-binoculars` and `fa-duotone fa-compass`, but this Kit doesn't include them: `binoculars` is missing the thin style, and `compass` isn't in the Kit at all. Those icons will not render. You can add them to your Kit at https://fontawesome.com/kits and re-run, choose a different Kit that includes them, or proceed and replace them with kit-available alternatives (try `/suggest-icon`).
+
+   Let the user decide how to proceed before finishing setup. Do not silently configure a Kit that omits icons the project already depends on.
+
+If the `fa` CLI isn't available or the user can't authenticate, note that you couldn't verify Kit coverage and that any icons missing from the Kit's subset won't render.
+
 ### 5. Verify the setup
 
 Add a test icon to confirm everything is working:

plugins/icons/skills/setup-fa/references/path-a-kit-embed.md

@@ -2,7 +2,7 @@
 
 1. Ask the user for their Kit code (the alphanumeric token, e.g., `abc123def4`). If they don't know it, direct them to https://fontawesome.com/kits to find it.
 2. Determine whether to use SVG+JS or Web Fonts+CSS delivery. Check the Kit's settings if possible:
-   - **`fa` CLI:** First verify auth by running `fa whoami`. If logged in (or `FA_API_TOKEN` is set), run `fa kits --kit-token <code>` to get the Kit's technology setting. If not authenticated, prompt the user to run `fa login` in a separate terminal first, or fall back below.
+   - **`fa` CLI:** First verify auth by running `fa whoami`. If logged in (or `FA_API_TOKEN` is set), run `fa kit show --kit-token <code>` to get the Kit's technology setting. If not authenticated, prompt the user to run `fa login` in a separate terminal first, or fall back below.
    - **Fallback:** Run `./scripts/fetch-kit.py --kit-id <code>` (in the `add-icon` skill directory).
    - If neither works, ask the user or default to SVG+JS.
 3. Add the embed code to the project's HTML `<head>`:

plugins/icons/skills/setup-fa/references/path-b-kit-npm.md

@@ -2,7 +2,7 @@
 
 1. Ask the user for their Kit code.
 2. Fetch Kit details to determine version and available families:
-   - **`fa` CLI:** First verify auth by running `fa whoami`. If logged in (or `FA_API_TOKEN` is set), run `fa kits --kit-token <code>` to get the Kit's technology setting. If not authenticated, prompt the user to run `fa login` in a separate terminal first, or fall back below.
+   - **`fa` CLI:** First verify auth by running `fa whoami`. If logged in (or `FA_API_TOKEN` is set), run `fa kit show --kit-token <code>` to get the Kit's technology setting. If not authenticated, prompt the user to run `fa login` in a separate terminal first, or fall back below.
    - **Fallback:** Run `./scripts/fetch-kit.py --kit-id <code>` (in the `add-icon` skill directory).
 3. Configure the npm registry for the `@awesome.me` scope. Add to `.npmrc` in the project root:
    ```

plugins/icons/skills/setup-fa/references/path-c-kit-download.md

@@ -9,8 +9,8 @@ This downloads a Kit's assets directly into the project — useful for self-host
    - If neither, tell the user:
      > You need to be logged in to the Font Awesome CLI to download your Kit. Run `fa login` in a separate terminal, then come back here and try again. Alternatively, set the `FA_API_TOKEN` environment variable with your API token from https://fontawesome.com/account/general.
 3. Determine the download type:
-   - **Web project:** `fa kits --kit-token <code> --download web --unzip --output <dir>`
-   - **Desktop project:** `fa kits --kit-token <code> --download desktop --unzip --output <dir>`
+   - **Web project:** `fa kit download --kit-token <code> --unzip --output <dir> web`
+   - **Desktop project:** `fa kit download --kit-token <code> --unzip --output <dir> desktop`
    Choose the output directory based on the project structure — e.g., `vendor/fontawesome`, `public/fontawesome`, `assets/fontawesome`, or ask the user.
 4. Run the download command and verify the files were extracted.
 5. For web projects, add the appropriate `<link>` or `<script>` tag pointing to the local files (follow the self-hosting docs fetched earlier).