feat: Clearer content regarding Butter CMS component library usage vs inline components

Author: jackdomleo7

README.md

@@ -47,10 +47,10 @@ Detect bloated HTML attributes introduced when content is pasted from external t
 - Shows context snippets around each finding for manual review
 
 ### Component Usage Audit
-Audit which of your known Butter CMS components are actually used across individual pages — complementing Butter CMS's built-in view, which shows which page types reference a component:
-- Add your component slugs to the Known Components configuration
+Audit which of your Butter CMS **component library** components are actually used across individual pages — complementing Butter CMS's built-in view, which shows which page types reference a component. This applies to reusable components created in the Butter CMS component library, not to inline components defined directly within a page type:
+- Add your component library slugs to the Component Library configuration
 - Scans all fields recursively — detects both object key-based and `type` field-based component references
-- Shows usage counts for each known component with a list of individual pages where it appears
+- Shows usage counts for each component library component with a list of individual pages where it appears
 - Warns when a component has zero individual page usages, noting that Butter CMS may still reference it at the page type level
 
 ## 🔧 Development

src/components/ApiConfiguration.spec.ts

@@ -809,7 +809,7 @@ describe('ApiConfiguration.vue', () => {
   describe('Known Components Section', () => {
     it('renders known components section heading', () => {
       const wrapper = mount(ApiConfiguration)
-      expect(wrapper.text()).toContain('Components')
+      expect(wrapper.text()).toContain('Component Library')
     })
 
     it('renders the known component TextInput', () => {
@@ -823,7 +823,7 @@ describe('ApiConfiguration.vue', () => {
       store.knownComponents = []
 
       const wrapper = mount(ApiConfiguration)
-      expect(wrapper.text()).toContain('No known components configured yet')
+      expect(wrapper.text()).toContain('No component library components configured yet')
     })
 
     it('does not show Add button when known component input is empty', () => {

src/components/ApiConfiguration.vue

@@ -121,7 +121,12 @@
 
       <!-- Components Section -->
       <div class="api-config__section">
-        <h3 class="api-config__section-title">Components</h3>
+        <h3 class="api-config__section-title">Component Library</h3>
+        <p class="api-config__section-description">
+          Add slugs for components from your Butter CMS <strong>component library</strong> only —
+          these are reusable, shared components created independently and added to page types.
+          Inline components defined directly within a page type are not tracked.
+        </p>
         <form @submit.prevent="addKnownComponent" novalidate class="api-config__form">
           <TextInput
             id="known-component-input"
@@ -130,7 +135,9 @@
             root-class="api-config__input"
             placeholder="e.g. hero_banner, cta_block, testimonial"
           >
-            <template v-slot:label>Add Component Slug (comma-separated for multiple)</template>
+            <template v-slot:label
+              >Add Component Library Slug (comma-separated for multiple)</template
+            >
           </TextInput>
           <Btn
             v-if="knownComponentInput"
@@ -147,7 +154,7 @@
             </Chip>
           </li>
         </ul>
-        <p v-else class="api-config__empty">No known components configured yet</p>
+        <p v-else class="api-config__empty">No component library components configured yet</p>
       </div>
     </div>
   </Accordion>
@@ -379,10 +386,17 @@ function removeKnownComponent(component: string): void {
   &__section-title {
     font-size: var(--font-size-lg);
     font-weight: 600;
-    margin: 0 0 var(--space-4) 0;
+    margin: 0 0 var(--space-2) 0;
     color: var(--text-primary);
   }
 
+  &__section-description {
+    font-size: var(--font-size-sm);
+    color: var(--text-secondary);
+    line-height: var(--line-height-relaxed);
+    margin: 0 0 var(--space-4) 0;
+  }
+
   &__form {
     display: flex;
     gap: var(--space-3);

src/components/Features/ComponentsContent.spec.ts

@@ -56,7 +56,7 @@ describe('ComponentsContent.vue', () => {
     it('shows warning when no known components configured', () => {
       store.knownComponents = []
       const wrapper = mountComponent()
-      expect(wrapper.text()).toContain('No known components configured')
+      expect(wrapper.text()).toContain('No known component library components configured')
     })
 
     it('does not show ScopeSelection when no known components configured', () => {

src/components/Features/ComponentsContent.vue

@@ -1,10 +1,15 @@
 <template>
   <UtilitySection
     title="Component Usage Audit"
-    description="Identify which of your known Butter CMS components are actually used across individual pages. Unlike Butter CMS's built-in view (which shows which page types reference a component), this tool shows which individual pages use each component — so you can spot components with zero real-world page usages."
+    description="Identify which of your Butter CMS component library components are actually used across individual pages. This applies to reusable components created in the Butter CMS component library — not to inline components defined directly within a page type. Unlike Butter CMS's built-in view (which shows which page types reference a component), this tool shows which individual pages use each component — so you can spot components with zero real-world page usages."
   >
     <!-- Info Banner -->
     <InfoBanner status="info" class="components-content__info">
+      <strong>Component library only:</strong> This tool tracks components from your Butter CMS
+      <em>component library</em> — reusable, shared components created independently and added to
+      page types. It does <strong>not</strong> track inline components defined directly within a
+      page type (local components that are not part of the shared library). Only add slugs for
+      component library components in API Configuration. <br /><br />
       <strong>Page types only:</strong> Components are only available in page types — blog posts and
       collections do not support Butter CMS components. Ensure all of your page types are added in
       API Configuration and all are selected below for a complete analysis. A component showing
@@ -19,8 +24,8 @@
 
     <!-- Guard: no known components configured -->
     <InfoBanner v-if="store.knownComponents.length === 0" status="warning">
-      No known components configured. Add your component slugs in
-      <strong>API Configuration → Known Components</strong> above to run an analysis.
+      No known component library components configured. Add your component library slugs in
+      <strong>API Configuration → Component Library</strong> above to run an analysis.
     </InfoBanner>
 
     <!-- Scope Selection (page types only) -->