@W-20593322 Developer Guidelines Tool

packages/b2c-dx-mcp/README.md

@@ -71,6 +71,86 @@ Override auto-discovery by specifying toolsets explicitly:
 "args": ["--working-directory", "${workspaceFolder}", "--toolsets", "CARTRIDGES,MRT", "--allow-non-ga-tools"]
 ```
 
+### Prompting Tips and Examples
+
+AI assistants (like Cursor, Claude Desktop) automatically decide which MCP tools to use based on your prompts. To get the best results, use clear, specific prompts that describe what you want to accomplish.
+
+> ⚠️ **IMPORTANT**: **Explicitly mention "Use the MCP tool"** in your prompts for reliable tool usage. While AI assistants (like Cursor's Composer) can automatically select MCP tools based on context, explicit instructions ensure the assistant prioritizes MCP tools over general knowledge, especially when multiple approaches are possible. This is particularly important for getting project-specific, up-to-date information rather than generic responses.
+
+#### Best Practices
+
+1. **Always explicitly request MCP tool usage** (see warning above): Start prompts with "Use the MCP tool to..." or include "Use the MCP tool" in your request.
+2. **Be specific about your goal**: Instead of "help me with Storefront Next", say "Use the MCP tool to show me how to build a product detail page with authentication"
+3. **Mention the tool or domain explicitly**: Reference the framework (Storefront Next, PWA Kit), operation (deploy, discover), or domain (SCAPI, cartridges)
+4. **Use natural language**: Describe what you want to achieve, not the tool name
+5. **Provide context**: Mention your project type, what you're building, or what you need to learn
+6. **Ask for guidelines first**: When starting a new project or learning a framework, ask for development guidelines before writing code
+
+#### Examples by Tool Category
+
+##### Storefront Next Development Guidelines
+
+The `storefront_next_development_guidelines` tool provides critical architecture rules and best practices. **Use this tool first** when starting new Storefront Next development or when you need architecture guidance.
+
+**Good prompts:**
+- ✅ "I'm new to Storefront Next. Use the MCP tool to show me the critical rules I need to know."
+- ✅ "I need to build a product detail page. Use the MCP tool to show me best practices for data fetching and component patterns."
+- ✅ "I need to build a checkout form with authentication and validation. Use the MCP tool to show me how to handle form submissions, authentication, and internationalized error messages."
+- ✅ "Use the MCP tool to show me the data fetching patterns for Storefront Next."
+- ✅ "Show me all available Storefront Next development guidelines."
+
+**Available sections:**
+- `quick-reference` - Critical rules and architecture principles (default)
+- `data-fetching` - Data loading patterns with loaders
+- `state-management` - Client-side state management
+- `auth` - Authentication and session management
+- `components` - Component patterns and best practices
+- `styling` - Tailwind CSS 4, Shadcn/ui, styling guidelines
+- `page-designer` - Page Designer integration
+- `performance` - Performance optimization
+- `testing` - Testing strategies
+- `i18n` - Internationalization patterns
+- `config` - Configuration management
+- `extensions` - Extension development
+- `pitfalls` - Common pitfalls
+
+##### PWA Kit Development
+
+**Good prompts:**
+- ✅ "I'm starting a new PWA Kit project. Use the MCP tool to get the development guidelines."
+- ✅ "Use the MCP tool to create a new product listing page component in my PWA Kit project."
+- ✅ "Use the MCP tool to recommend React hooks for fetching product data in PWA Kit."
+- ✅ "Use the MCP tool to explore the SCAPI Shop API endpoints available for my PWA Kit storefront."
+
+##### SCAPI Discovery
+
+**Good prompts:**
+- ✅ "Use the MCP tool to discover what SCAPI endpoints are available for product data."
+- ✅ "Use the MCP tool to discover custom SCAPI APIs in my B2C instance."
+- ✅ "Use the MCP tool to show me all available SCAPI endpoints and their capabilities."
+- ✅ "Use the MCP tool to scaffold a new custom SCAPI API for order management."
+
+##### Cartridge Deployment
+
+**Good prompts:**
+- ✅ "Use the MCP tool to deploy my cartridges to the sandbox instance."
+- ✅ "Use the MCP tool to deploy only the app_storefront_base cartridge to production."
+- ✅ "Use the MCP tool to deploy cartridges from the ./cartridges directory and reload the code version."
+
+##### MRT Bundle Operations
+
+**Good prompts:**
+- ✅ "Use the MCP tool to build and push my Storefront Next bundle to staging."
+- ✅ "Use the MCP tool to push the bundle from ./build directory to Managed Runtime."
+- ✅ "Use the MCP tool to deploy my PWA Kit bundle to production with a deployment message."
+
+#### Tips for Better Results
+
+- **Start with guidelines**: When learning a new framework, ask for development guidelines first using "Use the MCP tool to get..."
+- **Combine related topics**: Ask for multiple related sections (e.g., "data fetching and components") in one request
+- **Provide project context**: Mention your project type (Storefront Next, PWA Kit, cartridges) for better tool selection
+- **Specify operations clearly**: For deployment operations, mention the target (sandbox, staging, production) and what to deploy
+
 ### Configuration
 
 Credentials can be provided via **config files** (recommended), **environment variables**, or **flags**. Priority: Flags > Env vars > Config files.
@@ -205,13 +285,13 @@ Storefront Next development tools for building modern storefronts.
 
 | Tool | Description |
 |------|-------------|
-| `sfnext_development_guidelines` | Get Storefront Next development guidelines and best practices |
-| `sfnext_site_theming` | Configure and manage site theming for Storefront Next |
-| `sfnext_figma_to_component_workflow` | Convert Figma designs to Storefront Next components |
-| `sfnext_generate_component` | Generate a new Storefront Next component |
-| `sfnext_map_tokens_to_theme` | Map design tokens to Storefront Next theme configuration |
-| `sfnext_design_decorator` | Apply design decorators to Storefront Next components |
-| `sfnext_generate_page_designer_metadata` | Generate Page Designer metadata for Storefront Next components |
+| `storefront_next_development_guidelines` | Get Storefront Next development guidelines and best practices |
+| `storefront_next_site_theming` | Configure and manage site theming for Storefront Next |
+| `storefront_next_figma_to_component_workflow` | Convert Figma designs to Storefront Next components |
+| `storefront_next_generate_component` | Generate a new Storefront Next component |
+| `storefront_next_map_tokens_to_theme` | Map design tokens to Storefront Next theme configuration |
+| `storefront_next_design_decorator` | Apply design decorators to Storefront Next components |
+| `storefront_next_generate_page_designer_metadata` | Generate Page Designer metadata for Storefront Next components |
 | `scapi_discovery` | Discover available SCAPI endpoints and capabilities |
 | `scapi_custom_api_discovery` | Discover custom SCAPI API endpoints |
 | `mrt_bundle_push` | Build, push bundle (optionally deploy) |
@@ -287,7 +367,7 @@ npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools --me
 # Call a specific tool
 npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools \
   --method tools/call \
-  --tool-name sfnext_design_decorator
+  --tool-name storefront_next_design_decorator
 ```
 
 #### 2. IDE Integration

packages/b2c-dx-mcp/content/auth.md

@@ -0,0 +1,62 @@
+# Authentication & Session Management
+
+## Architecture
+
+Split-cookie architecture with server/client contexts:
+
+- **Server middleware** (`auth.server.ts`): Manages SLAS tokens, writes cookies
+- **Client middleware** (`auth.client.ts`): Reads cookies, maintains cache
+- **React Context** (`AuthProvider`): Provides auth state to components
+
+## Cookie Design
+
+| Cookie Name | Purpose | User Type | Expiry | HttpOnly |
+|-------------|---------|-----------|--------|----------|
+| `cc-nx-g` | Guest refresh token | Guest | 30 days | No |
+| `cc-nx` | Registered refresh token | Registered | 90 days | No |
+| `cc-at` | Access token | Both | 30 min | No |
+| `usid` | User session ID | Both | Matches refresh | No |
+| `customerId` | Customer ID | Registered | Matches refresh | No |
+
+**Key Points**:
+
+- Only ONE refresh token exists (guest OR registered, never both)
+- User type derived from which refresh token exists
+- Cookies auto-namespaced with `siteId`
+- Tokens auto-refresh when expired
+
+## Usage in Loaders/Actions
+
+```typescript
+import { getAuth } from '@/middlewares/auth.server';
+
+export function loader({ context }: LoaderFunctionArgs) {
+    const auth = getAuth(context);
+
+    // Access auth properties
+    const accessToken = auth.access_token;
+    const customerId = auth.customer_id;
+    const isGuest = auth.userType === 'guest';
+    const isRegistered = auth.userType === 'registered';
+
+    return { isGuest, customerId };
+}
+```
+
+## Usage in Components
+
+```typescript
+import { useAuth } from '@/providers/auth';
+
+export function MyComponent() {
+    const auth = useAuth();
+
+    if (auth?.userType === 'guest') {
+        return <LoginPrompt />;
+    }
+
+    return <div>Welcome, customer {auth?.customer_id}</div>;
+}
+```
+
+**Reference:** See README-AUTH.md for complete authentication documentation.

packages/b2c-dx-mcp/content/components.md

@@ -0,0 +1,123 @@
+# Component Patterns
+
+## Use the `createPage` HOC
+
+The `createPage` higher-order component standardizes page patterns with built-in Suspense and page key handling:
+
+```typescript
+import { use } from 'react';
+import { createPage } from '@/components/create-page';
+
+// Define your view component
+function ProductView({
+    product,
+    category
+}: {
+    product: Promise<Product>;
+    category?: Promise<Category>
+}) {
+    const productData = use(product);
+    const categoryData = category ? use(category) : null;
+
+    return (
+        <div>
+            <h1>{productData.name}</h1>
+            {categoryData && <p>Category: {categoryData.name}</p>}
+        </div>
+    );
+}
+
+// Create page with fallback
+const ProductPage = createPage({
+    component: ProductView,
+    fallback: <ProductSkeleton />
+});
+
+export default ProductPage;
+```
+
+**Benefits:**
+
+- Eliminates repetitive Suspense/Await boilerplate
+- Consistent loading states across pages
+- Built-in page key management for navigation transitions
+- Type-safe with full TypeScript support
+
+## shadcn/ui Components
+
+**RULES**:
+
+- ✅ Add via: `npx shadcn@latest add <component-name>`
+- ❌ DO NOT modify `src/components/ui/` directly
+- ✅ Create custom components elsewhere
+
+## Suspense Boundaries
+
+Use granular Suspense boundaries for better UX:
+
+```typescript
+// ✅ RECOMMENDED - Multiple Suspense boundaries
+export default function ProductPage({ loaderData: { product, reviews } }) {
+    return (
+        <div>
+            <Suspense fallback={<ProductHeaderSkeleton />}>
+                <Await resolve={product}>
+                    {(data) => <ProductHeader product={data} />}
+                </Await>
+            </Suspense>
+
+            <Suspense fallback={<ReviewsSkeleton />}>
+                <Await resolve={reviews}>
+                    {(data) => <ProductReviews reviews={data} />}
+                </Await>
+            </Suspense>
+        </div>
+    );
+}
+
+// ⚠️ OK - Single Suspense boundary (less granular)
+export default createPage({
+    component: ProductView,
+    fallback: <ProductPageSkeleton />
+});
+```
+
+## File Organization
+
+```
+src/components/product-tile/
+├── index.tsx              # Component
+├── index.test.tsx         # Tests
+└── stories/
+    ├── index.stories.tsx  # Storybook stories
+    └── __snapshots__/     # Storybook snapshots (optional)
+        └── product-tile-snapshot.tsx.snap
+
+# Skeleton components are separate components
+src/components/product-skeleton/
+├── index.tsx
+├── index.test.tsx
+└── stories/
+    └── index.stories.tsx
+```
+
+## Styling
+
+**Tailwind CSS 4** is the only styling approach allowed. Use utility classes directly in components.
+
+**Key rules:**
+
+- ✅ Use Tailwind utility classes
+- ✅ Use `cn()` utility for conditional classes
+- ❌ NO inline styles, NO CSS modules, NO separate CSS files
+
+**See `styling` section for:** Tailwind CSS 4, Shadcn/ui components, icons, responsive design, theme configuration, dark mode, best practices
+
+## Best Practices
+
+1. **Extract view components** - Separate data handling from presentation
+2. **Type safety** - Define proper TypeScript interfaces
+3. **Consistent fallbacks** - Reusable skeleton components
+4. **Colocate tests** - Keep tests next to components
+5. **Story coverage** - Create stories for all reusable components
+6. **Tailwind utilities only** - Use Tailwind CSS classes, avoid inline styles or CSS modules