@salesforce/templates 66.5.6 → 66.6.0

package/lib/templates/project/reactb2x/_r_/skills/installing-webapp-features/SKILL.md

@@ -1,210 +0,0 @@
----
-name: installing-webapp-features
-description: Search, describe, and install pre-built UI features (authentication, shadcn components, navigation, search, GraphQL, Agentforce AI) into Salesforce webapps. Use this when the user wants to add functionality to a webapp, or when determining what salesforce-provided features are available — whether prompted by the user or on your own initiative. Always check for an existing feature before building from scratch.
----
-
-# webapps-features-experimental CLI — Agent Reference
-
-**Always check for an existing feature before building something yourself.** This CLI installs pre-built, tested feature packages into Salesforce webapps. Features range from foundational UI component libraries (shadcn/ui with Button, Card, Input, Table, etc.) to full-stack application capabilities like authentication (login, registration, password flows, session management, and Apex backend classes), global search, navigation menus, GraphQL integrations, and Agentforce AI conversation UIs. Each feature ships as a complete implementation — including React components, context providers, route guards, and any required Salesforce server-side code — that already handles platform-specific concerns like Salesforce API integration, session management, and SFDX metadata structure. Building these from scratch is error-prone and unnecessary when a feature exists. **If no existing feature is found, ask the user before proceeding with a custom implementation — a relevant feature may exist under a different name or keyword.**
-
-```
-npx @salesforce/webapps-features-experimental <command> [options]
-```
-
-## Workflow: Search Project → Search Features → Describe → Install
-
-**MANDATORY**: When the user asks to add ANY webapp functionality, follow this entire workflow. Do not skip steps.
-
-### 1. Search existing project code
-
-Before installing anything, check whether the functionality already exists in the **project source code** (not dependencies).
-
-- **Always scope searches to `src/`** to avoid matching files in `node_modules/`, `dist/`, or `build/` output
-- Use Glob with a scoped path: e.g., `src/**/Button.tsx`, `src/**/*auth*.tsx`
-- Use Grep with the `path` parameter set to the `src/` directory, or use `glob: "*.{ts,tsx}"` to restrict file types
-- Check common directories: `src/components/`, `src/lib/`, `src/pages/`, `src/hooks/`
-- **Never** search from the project root without a path or glob filter — this will crawl `node_modules` and produce massive, unhelpful output
-
-**If existing code is found** — read the files, present them to the user, and ask if they want to reuse or extend what's there. If yes, use the existing code and stop. If no, proceed to step 2.
-
-**If nothing is found** — proceed to step 2.
-
-### 2. Search available features
-
-```bash
-npx @salesforce/webapps-features-experimental list [options]
-```
-
-Options:
-
-- `-v, --verbose` — Show full descriptions, packages, and dependencies
-- `--search <query>` — Filter features by keyword (ranked by relevance)
-
-```bash
-npx @salesforce/webapps-features-experimental list
-npx @salesforce/webapps-features-experimental list --search "auth"
-npx @salesforce/webapps-features-experimental list --search "button"
-```
-
-**If no matching feature is found** — ask the user before proceeding with a custom implementation. A relevant feature may exist under a different name or keyword.
-
-### 3. Describe a feature
-
-```bash
-npx @salesforce/webapps-features-experimental describe <feature>
-```
-
-Shows description, package name, dependencies, components, copy operations, and example files.
-
-```bash
-npx @salesforce/webapps-features-experimental describe authentication
-npx @salesforce/webapps-features-experimental describe shadcn
-```
-
-### 4. Install a feature
-
-```bash
-npx @salesforce/webapps-features-experimental install <feature> --webapp-dir <path> [options]
-```
-
-Resolves the feature name to an npm package, installs it and its dependencies (including transitive feature dependencies like `shadcn`), copies source files into your project, and reports any `__example__` files that require manual integration.
-
-Options:
-
-- `--webapp-dir <name>` (required) — Webapp name, resolves to `<sfdx-source>/webapplications/<name>`
-- `--sfdx-source <path>` (default: `force-app/main/default`) — SFDX source directory
-- `--dry-run` (default: `false`) — Preview changes without writing files
-- `-v, --verbose` (default: `false`) — Enable verbose logging
-- `-y, --yes` (default: `false`) — Skip all prompts (auto-skip conflicts)
-- `--on-conflict <mode>` (default: `prompt`) — `prompt`, `error`, `skip`, or `overwrite`
-- `--conflict-resolution <file>` — Path to JSON file with per-file resolutions
-
-```bash
-# Install authentication (also installs shadcn dependency)
-npx @salesforce/webapps-features-experimental install authentication \
-  --webapp-dir mywebapp
-
-# Dry run to preview changes
-npx @salesforce/webapps-features-experimental install shadcn \
-  --webapp-dir mywebapp \
-  --dry-run
-
-# Non-interactive install (skip all file conflicts)
-npx @salesforce/webapps-features-experimental install authentication \
-  --webapp-dir mywebapp \
-  --yes
-```
-
-## Conflict Handling
-
-Since you are running in a non-interactive environment, you cannot use `--on-conflict prompt` directly. When conflicts are likely (e.g. installing into an existing project), you have two options:
-
-**Option A — Let the user resolve conflicts interactively.** Suggest the user run the install command themselves with `--on-conflict prompt` so they can decide per-file.
-
-**Option B — Two-pass automated resolution:**
-
-```bash
-# Pass 1: detect conflicts
-npx @salesforce/webapps-features-experimental install authentication \
-  --webapp-dir mywebapp \
-  --on-conflict error
-
-# The CLI will exit with an error listing every conflicting file path.
-
-# Pass 2: create a resolution file and re-run
-echo '{ "src/styles/global.css": "overwrite", "src/lib/utils.ts": "skip" }' > resolutions.json
-
-npx @salesforce/webapps-features-experimental install authentication \
-  --webapp-dir mywebapp \
-  --conflict-resolution resolutions.json
-```
-
-Resolution values per file: `"skip"` (keep existing) or `"overwrite"` (replace). When unsure how to resolve a conflict, ask the user rather than guessing.
-
-## Hint Placeholders in Copy Paths
-
-Some copy operations use **hint placeholders** in the `"to"` path — descriptive segments like `<desired-page-with-search-input>` that are NOT resolved by the CLI. These are guidance for the user or LLM to choose an appropriate destination.
-
-**How they work:** The file is copied with the literal placeholder name (e.g., `src/pages/<desired-page-with-search-input>.tsx`). After installation, you should:
-
-1. Read the copied file to understand its purpose
-2. Rename or relocate it to the intended target (e.g., `src/pages/Home.tsx`)
-3. Or integrate its patterns into an existing file, then delete it
-
-**How to identify them:** Hint placeholders use `<descriptive-name>` syntax but are NOT one of the system placeholders (`<sfdxSource>`, `<webappDir>`, `<webapp>`). They always appear in the middle or end of a path, never as the leading segment.
-
-**Example from features.json:**
-
-```json
-{
-  "to": "<webappDir>/src/pages/<desired-page-with-search-input>.tsx",
-  "description": "Example home page showing GlobalSearchInput integration",
-  "integrationTarget": "src/pages/Home.tsx"
-}
-```
-
-The `integrationTarget` field tells you the suggested destination. Use your judgment — if the user already has a different page where search should go, integrate there instead.
-
-**When `integrationTarget` itself is a placeholder:** Some features use a hint placeholder in the `integrationTarget` value (e.g., `"integrationTarget": "src/<path-to-desired-page-with-search-input>.tsx"`). This means there is no single default target — the user must decide which existing file to integrate into. When you encounter this:
-
-1. Ask the user which page or file they want to integrate the feature into
-2. Read the `__example__` file to understand the integration pattern
-3. Read the user's chosen target file
-4. Apply the pattern from the example into the target file
-
-## Post Installation: Integrating **example** Files
-
-Features may include `__example__` files (e.g., `__example__auth-app.tsx`) showing integration patterns.
-
-**The describe command shows**:
-
-- Which **example** files will be copied
-- Target file to integrate into (e.g., `src/app.tsx`)
-- What the example demonstrates
-
-### How to Integrate Example Files (CRITICAL FOR LLMs)
-
-⚠️ **ONLY USE Read AND Edit TOOLS - NO BASH COMMANDS** ⚠️
-
-**DO NOT DO THIS**:
-
-- ❌ `git status` or any git commands
-- ❌ `ls`, `cat`, `sed`, `awk`, or ANY bash file commands
-- ❌ Chaining bash commands to read multiple files
-- ❌ Using bash to check directories or file existence
-
-**DO THIS INSTEAD**:
-
-- ✅ Use Read tool with `file_path` parameter to read each file
-- ✅ Use Edit tool with `file_path`, `old_string`, `new_string` to modify files
-- ✅ That's it! Just Read and Edit tools.
-
-**Integration steps**:
-
-1. **Read each example file** (use Read tool)
-   - Example: Read tool with `file_path: "force-app/main/default/webapplications/mywebapp/src/__example__auth-app.tsx"`
-   - Note the imports and patterns to integrate
-
-2. **Read each target file** (use Read tool)
-   - Example: Read tool with `file_path: "force-app/main/default/webapplications/mywebapp/src/app.tsx"`
-   - Understand where the new code should go
-
-3. **Edit each target file** (use Edit tool)
-   - Add imports from the example
-   - Add or modify code following the example's patterns
-   - Preserve existing functionality
-
-4. **Delete the example file after successful integration** (use Bash tool)
-   - Example: `rm force-app/main/default/webapplications/mywebapp/src/__example__authentication-routes.tsx`
-   - Only delete after you have successfully integrated the pattern
-   - This keeps the codebase clean and removes temporary example files
-
-## Troubleshooting
-
-**Directory not found**: Check paths are correct, use absolute or correct relative paths
-
-**Feature not found**: Use `npx @salesforce/webapps-features-experimental list` to see available feature names
-
-**Conflicts in error mode**: Follow CLI instructions to create resolution file
-
-**Need help?**: Run `npx @salesforce/webapps-features-experimental --help` to see all commands and options

package/lib/templates/project/reactb2x/_r_/skills/managing-agentforce-conversation-client/SKILL.md

@@ -1,186 +0,0 @@
----
-name: managing-agentforce-conversation-client
-description: Adds or modifies AgentforceConversationClient in React apps (.tsx or .jsx files). Use when user says "add chat widget", "embed agentforce", "add agent", "add chatbot", "integrate conversational AI", or asks to change colors, dimensions, styling, or configure agentId, width, height, inline mode, or styleTokens for travel agent, HR agent, employee agent, or any Salesforce agent chat.
-metadata:
-  author: ACC Components
-  version: 1.0.0
-  package: "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental"
-  sdk-package: "@salesforce/agentforce-conversation-client"
-  last-updated: 2025-03-18
----
-
-# Managing Agentforce Conversation Client
-
-## Instructions
-
-### Step 1: Check if component already exists
-
-Search for existing usage across all app files (not implementation files):
-
-```bash
-grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules
-```
-
-**Important:** Look for React files that import and USE the component (for example, shared shells, route components, or feature pages). Do NOT open files named `AgentforceConversationClient.tsx` or `AgentforceConversationClient.jsx` - those are the component implementation.
-
-**If found:** Read the file and check the current `agentId` value.
-
-**Agent ID validation rule (deterministic):**
-
-- Valid only if it matches: `^0Xx[a-zA-Z0-9]{15}$`
-- Meaning: starts with `0Xx` and total length is 18 characters
-
-**Decision:**
-
-- If `agentId` matches `^0Xx[a-zA-Z0-9]{15}$` and user wants to update other props → Go to Step 4 (update props)
-- If `agentId` is missing, empty, or does NOT match `^0Xx[a-zA-Z0-9]{15}$` → Continue to Step 2 (need real ID)
-- If not found → Continue to Step 2 (add new)
-
-### Step 2: Get agent ID
-
-If component doesn't exist or has an invalid placeholder value, ask user for their Salesforce agent ID.
-
-Treat these as placeholder/invalid values:
-
-- `"0Xx..."`
-- `"Placeholder"`
-- `"YOUR_AGENT_ID"`
-- `"<USER_AGENT_ID_18_CHAR_0Xx...>"`
-- Any value that does not match `^0Xx[a-zA-Z0-9]{15}$`
-
-Skip this step if:
-
-- Component exists with a real agent ID
-- User only wants to update styling or dimensions
-
-### Step 3: Canonical import strategy
-
-Use this import path by default in app code:
-
-```tsx
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
-```
-
-If the package is not installed, install it:
-
-```bash
-npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
-```
-
-Only use a local relative import (for example, `./components/AgentforceConversationClient`) when the user explicitly asks to use a patched/local component in that app.
-
-Do not infer import path from file discovery alone. Prefer one consistent package import across the codebase.
-
-### Step 4: Add or update component
-
-**For new installations:**
-
-Add to the target React component file using the canonical package import:
-
-```tsx
-import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
-
-export default function AgentChatHost() {
-  return (
-    <>
-      <Outlet />
-      <AgentforceConversationClient agentId="0Xx..." />
-    </>
-  );
-}
-```
-
-**Fallback note:** Use a local relative import only when the user explicitly requests patched/local component usage in that app.
-
-**For updates:**
-
-Read the file where component is used and modify only the props that need to change. Preserve all other props. Never delete and recreate.
-
-**Replacing placeholder values:**
-
-If the component has a placeholder agentId (e.g., `agentId="Placeholder"` or `agentId="0Xx..."`), replace it with the real agent ID:
-
-```tsx
-// Before (template with placeholder)
-<AgentforceConversationClient agentId="Placeholder" />
-
-// After (with real agent ID)
-<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />
-```
-
-### Step 5: Configure props
-
-**Available props (use directly on component):**
-
-- `agentId` (string, required) - Salesforce agent ID
-- `inline` (boolean) - `true` for inline mode, omit for floating
-- `width` (number | string) - e.g., `420` or `"100%"`
-- `height` (number | string) - e.g., `600` or `"80vh"`
-- `headerEnabled` (boolean) - Show/hide header
-- `styleTokens` (object) - For all styling (colors, fonts, spacing)
-- `salesforceOrigin` (string) - Auto-resolved
-- `frontdoorUrl` (string) - Auto-resolved
-
-**Examples:**
-
-Floating mode (default):
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." />
-```
-
-Inline mode with dimensions:
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." inline width="420px" height="600px" />
-```
-
-Styling with styleTokens:
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  styleTokens={{
-    headerBlockBackground: "#0176d3",
-    headerBlockTextColor: "#ffffff",
-    messageBlockInboundBackgroundColor: "#4CAF50",
-  }}
-/>
-```
-
-**For complex patterns,** consult `references/examples.md` for:
-
-- Sidebar containers and responsive sizing
-- Dark theme and advanced theming combinations
-- Inline without header, calculated dimensions
-- Complete host component examples
-
-**For styling:** For ANY color, font, or spacing changes, use `styleTokens` prop only. See `references/style-tokens.md` for complete token list and examples.
-
-**Common mistakes to avoid:** Consult `references/constraints.md` for:
-
-- Invalid props (containerStyle, style, className)
-- Invalid styling approaches (CSS files, style tags)
-- What files NOT to edit (implementation files)
-
-## Common Issues
-
-If component doesn't appear or authentication fails, see `references/troubleshooting.md` for:
-
-- Agent activation and deployment
-- Localhost trusted domains
-- Cookie restriction settings
-
-## Prerequisites
-
-Before the component will work, the following Salesforce settings must be configured by the user:
-
-**Cookie settings:**
-
-- Setup → My Domain → Disable "Require first party use of Salesforce cookies"
-
-**Trusted domains (required only for local development):**
-
-- Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
-  - Local development: `localhost:<PORT>` (e.g., `localhost:3000`)

package/lib/templates/project/reactb2x/_r_/skills/managing-agentforce-conversation-client/references/constraints.md

@@ -1,134 +0,0 @@
-# Constraints and Anti-Patterns
-
-This document lists all invalid approaches and patterns to avoid when working with AgentforceConversationClient.
-
-## Never Edit Implementation Files
-
-**CRITICAL: Only edit files where the component is USED, never the component implementation itself.**
-
-- ✅ **DO edit**: Any React files that import and use `<AgentforceConversationClient />` (for example, shared shells, route components, or feature pages)
-- ❌ **DO NOT edit**: AgentforceConversationClient.tsx, AgentforceConversationClient.jsx, index.tsx, index.jsx, or any files inside:
-  - `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/`
-  - `packages/template/feature/feature-react-agentforce-conversation-client/src/`
-  - `src/components/AgentforceConversationClient.tsx` (patched templates)
-  - Any path containing `/components/AgentforceConversationClient.`
-
-**If you're reading a file named `AgentforceConversationClient.tsx`, you're in the wrong place. Stop and search for the USAGE instead.**
-
-## Invalid Props
-
-AgentforceConversationClient uses a flat prop API and does NOT accept these props:
-
-- ❌ `containerStyle` - Use `width` and `height` props directly instead
-- ❌ `style` - Use `styleTokens` for theming
-- ❌ `className` - Not supported
-- ❌ Any standard React div props - This wraps an embedded iframe, not a div
-
-**Why:** The component is a wrapper around an embedded iframe using Lightning Out 2.0. Standard React styling props don't apply.
-
-## Invalid Styling Approaches
-
-**CRITICAL: For ALL styling, theming, branding, or color changes - ONLY use `styleTokens` prop.**
-
-Never use these approaches:
-
-- ❌ Creating CSS files (e.g., `agent-styles.css`, `theme.css`)
-- ❌ Creating `<style>` tags or internal stylesheets
-- ❌ Using `style` attribute on the component
-- ❌ Using `className` prop
-- ❌ Inline styles
-- ❌ CSS modules
-- ❌ Styled-components or any CSS-in-JS libraries
-
-**Why:** The component controls its own internal styling through the `styleTokens` API. External CSS cannot reach into the embedded iframe.
-
-## Invalid Implementation Approaches
-
-Never do these:
-
-- ❌ Create custom chat UIs from scratch
-- ❌ Use third-party chat libraries (socket.io, WebSocket libraries, etc.)
-- ❌ Call `embedAgentforceClient` directly from `@salesforce/agentforce-conversation-client`
-- ❌ Build custom WebSocket or REST API chat implementations
-
-**Why:** The AgentforceConversationClient component is the official wrapper that handles authentication, Lightning Out 2.0 initialization, and all communication with Salesforce agents. Custom implementations will not work.
-
-## Invalid Update Patterns
-
-When updating an existing component:
-
-- ❌ Delete and recreate the component
-- ❌ Remove all props and start over
-- ❌ Copy the entire component to a new file
-
-**Why:** This loses configuration, introduces errors, and creates unnecessary diffs. Always update props in place.
-
-## Examples
-
-### ❌ Wrong - Using containerStyle
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." containerStyle={{ width: 420, height: 600 }} />
-```
-
-### ✅ Correct - Using width/height directly
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." width="420px" height="600px" />
-```
-
-### ❌ Wrong - Creating CSS file
-
-```css
-/* agent-styles.css */
-.agentforce-chat {
-  background: red;
-  color: white;
-}
-```
-
-```tsx
-import "./agent-styles.css";
-
-<AgentforceConversationClient className="agentforce-chat" />;
-```
-
-### ✅ Correct - Using styleTokens
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  styleTokens={{
-    headerBlockBackground: "red",
-    headerBlockTextColor: "white",
-  }}
-/>
-```
-
-### ❌ Wrong - Creating style tag
-
-```tsx
-<>
-  <style>{`.agent-chat { background: blue; }`}</style>
-  <AgentforceConversationClient agentId="0Xx..." />
-</>
-```
-
-### ✅ Correct - Using styleTokens
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  styleTokens={{
-    headerBlockBackground: "blue",
-  }}
-/>
-```
-
-### ❌ Wrong - Editing implementation file
-
-Reading or editing: `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/AgentforceConversationClient.tsx`
-
-### ✅ Correct - Editing usage file
-
-Reading and editing: usage files where the component is imported and used (for example, `src/app.tsx`, a route component, or a feature page)

package/lib/templates/project/reactb2x/_r_/skills/managing-agentforce-conversation-client/references/examples.md

@@ -1,132 +0,0 @@
-# Additional Examples
-
-Essential examples for common patterns and combinations. All use flat props API.
-
----
-
-## Layout Patterns
-
-### Sidebar Chat
-
-```tsx
-export default function DashboardWithChat() {
-  return (
-    <div style={{ display: "flex", height: "100vh" }}>
-      <main style={{ flex: 1 }}>{/* Main content */}</main>
-      <aside style={{ width: 400 }}>
-        <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="100%" />
-      </aside>
-    </div>
-  );
-}
-```
-
-### Full Page Chat
-
-```tsx
-export default function SupportPage() {
-  return (
-    <div>
-      <h1>Customer Support</h1>
-      <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="600px" />
-    </div>
-  );
-}
-```
-
----
-
-## Size Variations
-
-### Responsive sizing
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." inline width="100%" height="80vh" />
-```
-
-### Calculated dimensions
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." inline width="500px" height="calc(100vh - 100px)" />
-```
-
----
-
-## Theming Combinations
-
-### Brand theme with custom sizing
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  inline
-  width="500px"
-  height="700px"
-  styleTokens={{
-    headerBlockBackground: "#0176d3",
-    headerBlockTextColor: "#ffffff",
-    messageBlockInboundBackgroundColor: "#0176d3",
-    messageBlockInboundTextColor: "#ffffff",
-    messageInputFooterSendButton: "#0176d3",
-  }}
-/>
-```
-
-### Dark theme
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  styleTokens={{
-    headerBlockBackground: "#1a1a1a",
-    headerBlockTextColor: "#ffffff",
-    messageBlockInboundBackgroundColor: "#2d2d2d",
-    messageBlockInboundTextColor: "#ffffff",
-    messageBlockOutboundBackgroundColor: "#3a3a3a",
-    messageBlockOutboundTextColor: "#f0f0f0",
-  }}
-/>
-```
-
-### Inline without header
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  inline
-  width="100%"
-  height="600px"
-  headerEnabled={false}
-  styleTokens={{
-    messageBlockBorderRadius: "12px",
-  }}
-/>
-```
-
----
-
-## Complete Host Component Example
-
-```tsx
-import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
-
-export default function AgentChatHost() {
-  return (
-    <>
-      <Outlet />
-      <AgentforceConversationClient
-        agentId="0Xx..."
-        styleTokens={{
-          headerBlockBackground: "#0176d3",
-          headerBlockTextColor: "#ffffff",
-        }}
-      />
-    </>
-  );
-}
-```
-
----
-
-For complete style token reference, see `references/style-tokens.md` or `node_modules/@salesforce/agentforce-conversation-client/README.md`.