sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/skills/sfcc-caching/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: sfcc-caching
+description: Unified caching playbook for SFCC (page cache vs custom cache vs service response cache). Use this when improving performance, reducing external calls, designing cache keys/TTLs, or debugging stale cache behavior.
+---
+
+# SFCC Caching (Unified Playbook)
+
+Caching in SFCC has multiple layers. The most common failures come from:
+- choosing the wrong cache layer
+- unsafe population patterns
+- invalidation assumptions (multi-node)
+- caching the wrong data types (heavy API objects)
+
+## Quick Checklist
+
+```text
+[ ] Choose cache layer: page cache (HTML) vs custom cache (data) vs service response cache
+[ ] Design keys with site + locale scoping where needed
+[ ] Use atomic get-or-load patterns (avoid double loaders)
+[ ] Cache POJOs/DTOs, not dw.* API objects
+[ ] Treat cache values as immutable snapshots; re-put updated copies
+[ ] Design around TTL, not cross-node invalidation
+[ ] Monitor hit ratios and write failures in Business Manager
+```
+
+## Cache Layers (Pick the Right Tool)
+
+| Layer | What it caches | When to use |
+|---|---|---|
+| Page cache | Rendered responses / fragments | High-traffic pages where output can be cached |
+| Custom cache (`CacheMgr`) | Application data | Expensive computations, repeated DB lookups, third-party responses |
+| Service response cache | HTTP responses inside service framework | Repeated calls to stable third-party APIs |
+
+## Scope: request vs session vs CacheMgr
+
+- `request.custom`: per-request scratchpad
+- `session.custom` / `session.privacy`: per-user, per-session data (keep small)
+- `CacheMgr`: app-server local cache shared by users on the same node
+
+Never store user-specific data in a global custom cache.
+
+## Custom Cache Mechanics (Non-Negotiable Rules)
+
+### 1) Define caches in `caches.json` and register in cartridge `package.json`
+- Cache IDs must be globally unique across the cartridge path.
+- The `package.json` that declares `"caches"` must live in the cartridge root (cartridges/{{mycartridge}}/package.json), and the `caches.json` path is relative to that.
+
+### 2) Use atomic “get-or-load”
+Prefer `cache.get(key, loader)` (single step). Avoid:
+- `if (!cache.get(key)) cache.put(key, load())`
+
+### 3) Cache POJOs, not API objects
+Don’t cache `dw.catalog.Product`, `dw.order.Order`, etc.
+Map to a lightweight object with only the fields you need.
+
+### 4) Treat cached values as immutable
+Values returned by `cache.get` are immutable copies. Do not mutate them in-place.
+If you need to update cached data, write a new object back with `cache.put(key, newValue)`.
+
+### 5) TTL over invalidation
+Per-key invalidation across all nodes is unreliable.
+Design for a small staleness window using `expireAfterSeconds`.
+
+### 6) Watch size limits and monitoring
+- Large entries can fail to store without throwing exceptions.
+- Use Business Manager stats (hit ratio, write failures) to validate effectiveness.
+
+## Service Response Caching (LocalServiceRegistry)
+
+If your third-party data is stable for short periods:
+- Enable response caching on the underlying HTTP client in the service definition
+- Ensure you understand how to clear it (BM invalidation is typically global)
+
+Key warnings:
+- stale data risk
+- debugging surprises (you may not hit the network)
+- cached calls can still affect service stats / circuit breakers
+
+## References
+- Rhino Inquisitor: Field Guide to Custom Caches
+  - https://www.rhino-inquisitor.com/field-guide-to-custom-caches-in-sfcc/
+- Rhino Inquisitor: Third-Party API Caching in Commerce Cloud
+  - https://www.rhino-inquisitor.com/third-party-api-caching-in-commerce-cloud/
+- SFCC Docs: Custom Caches
+  - https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-custom-caches.html
+- SFCC Script API: `dw.system.Cache` (immutable copies + value constraints)
+  - https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_system_Cache.html
+- SFCC Script API: `dw.system.CacheMgr` (cartridge `package.json` cache registration)
+  - https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_system_CacheMgr.html

package/{dist/docs/best-practices/cartridge_creation.md → ai-instructions/skills/sfcc-cartridge-development/SKILL.md}

@@ -1,8 +1,13 @@
+---
+name: sfcc-cartridge-development
+description: Guide for creating, configuring, and deploying custom SFRA cartridges in Salesforce B2C Commerce. Use this when asked to create a new cartridge, set up a cartridge structure, or work with cartridge paths.
+---
+
 # Instructions for Creating a Salesforce B2C Commerce (SFRA) Cartridge
 
 This document provides instructions to create, configure, and deploy a new custom cartridge for Salesforce B2C Commerce using the Storefront Reference Architecture (SFRA).
 
-**NOTE**: When doing this, also request best practices for controller creation from this MCP server. Additionally, consult the **Performance and Stability Best Practices** guide from this MCP server to ensure your cartridge follows performance optimization strategies and coding standards.
+**NOTE**: When doing this, also consult the **sfcc-sfra-controllers** skill for controller development patterns and the **sfcc-performance** skill to ensure your cartridge follows performance optimization strategies and coding standards.
 
 ## 1. Core Principles
 
@@ -60,6 +65,7 @@ dw.json
 webpack.config.js           
 cartridges/
 └── plugin_my_custom_cartridge/
+    |── package.json
     └── cartridge/
         ├── client/             
         │   └── default/
@@ -79,6 +85,25 @@ Optional but common directories:
 - `cartridge/scripts/jobs/`: Scripts for automated tasks scheduled in Business Manager.
 - `cartridge/properties/`: Localization string files (.properties).
 
+## 4.1 Cartridge `package.json` Capabilities (Often Missed)
+
+Beyond basic metadata, `package.json` can declare cartridge-owned configuration files that the platform consumes.
+  The `package.json` must be in the cartridge root (cartridges/{{mycartridge}}/package.json), and paths are relative to that.
+
+- **Hooks**: add a `hooks` entry pointing to your `hooks.json` (commonly under `cartridge/scripts/hooks.json`).
+- **Custom Caches**: add a `caches` entry pointing to `caches.json` so `CacheMgr.getCache('<id>')` can resolve your cache.
+- **Custom SCAPI APIs**: custom endpoints live under `cartridge/rest-apis/{api-name}/` (with `schema.yaml`, `script.js`, `api.json`).
+
+Example snippet:
+
+```json
+{
+    "name": "plugin_my_custom_cartridge",
+    "hooks": "./cartridge/scripts/hooks.json",
+    "caches": "./caches.json"
+}
+```
+
 ## 5. Creating a New Cartridge
 
 ### Step 1: Generate the Cartridge Structure
@@ -86,7 +111,7 @@ Optional but common directories:
 !IMPORTANT!: Always do this step, don't attempt to create the cartridge structure manually. The MCP server ensures all necessary files and configurations are created correctly.
 
 **Using MCP Server (Recommended)**
-Use the `generate_cartridge_structure` tool from this MCP server to automatically create the cartridge structure:
+Use the `generate_cartridge_structure` tool from the sfcc-dev-mcp server to automatically create the cartridge structure:
 
 ```json
 {
@@ -190,14 +215,13 @@ For continuous development, use `npm run watch`.
 
 ## 9. MCP Integration Workflow
 
-When using this MCP server for cartridge development, follow this enhanced workflow:
+When using the sfcc-dev-mcp server for cartridge development, follow this enhanced workflow:
 
 1. **Generate Cartridge Structure**: Use the `generate_cartridge_structure` tool to create the initial cartridge with all necessary files and configurations
-2. **Get Best Practices**: Use `get_best_practice_guide` with "sfra_controllers" for controller development patterns
+2. **Consult Skills**: Use the relevant skills for controller development patterns (sfcc-sfra-controllers), security (sfcc-security), and performance (sfcc-performance)
 3. **Search Documentation**: Use `search_sfcc_classes` and `get_sfcc_class_info` for API reference
-4. **Validate Implementation**: Use `search_best_practices` to ensure your code follows security and performance guidelines
-5. **Debug Issues**: Use log analysis tools to troubleshoot deployment or runtime issues
-6. **Handle Deployment Issues**: If new cartridge features (jobs, SCAPI endpoints, hooks) don't appear after upload:
+4. **Debug Issues**: Use log analysis tools to troubleshoot deployment or runtime issues
+5. **Handle Deployment Issues**: If new cartridge features (jobs, SCAPI endpoints, hooks) don't appear after upload:
    - **Check Code Versions**: Use `get_code_versions` tool to see available versions
    - **Activate Version**: Use `activate_code_version` tool to ensure proper registration
    - **Alternative**: Manually switch code versions in Business Manager (Administration > Site Development > Code Deployment)

package/ai-instructions/skills/sfcc-forms-development/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: sfcc-forms-development
+description: Guide for building, validating, securing, and persisting SFCC storefront forms (SFRA + SiteGenesis patterns). Use this when creating or troubleshooting form XML, controller handling, CSRF, and validation.
+---
+
+# SFCC Forms Development Skill
+
+This skill guides you through implementing and troubleshooting the Salesforce B2C Commerce Forms Framework.
+
+It covers:
+- XML form definitions (schema, constraints, localization, reuse)
+- Controller patterns (SFRA middleware, request handling, persistence)
+- Secure validation (server-side first, CSRF/XSS protections)
+- Migration guidance (SiteGenesis ➜ SFRA)
+
+## When to Use
+
+Use this skill when you need to:
+- Create or modify a form definition in `cartridge/forms/**`.
+- Render forms in ISML using the platform’s generated field metadata.
+- Process POST submissions safely (CSRF, server-side validation, transactions).
+- Add custom validation beyond XML constraints.
+- Migrate legacy SiteGenesis form flows to SFRA.
+
+## Quick Checklist (Production-Grade Forms)
+
+```text
+[ ] Form routes are POST-only and HTTPS-only
+[ ] CSRF token is generated on GET and validated on POST
+[ ] Server-side validation gate exists (do not trust client validation)
+[ ] All string fields have max-length (DoS & storage safety)
+[ ] Regex is conservative (avoid catastrophic backtracking)
+[ ] Persistence happens inside Transaction.wrap
+[ ] SFRA persistence is isolated in route:BeforeComplete where appropriate
+[ ] Explicit mapping for writes (avoid mass assignment)
+[ ] Form state cleared when appropriate (pre-render or after success)
+[ ] User-provided values are output-encoded in ISML
+```
+
+## File Locations
+
+### Form XML
+
+Forms are defined per cartridge:
+
+```
+/my-cartridge
+  /cartridge
+    /forms
+      /default
+        profile.xml
+        contact.xml
+      /de_DE
+        profile.xml
+```
+
+### Form Labels + Error Messages (Localization)
+
+Resource bundles typically live in:
+
+```
+/my-cartridge
+  /cartridge
+    /templates
+      /resources
+        forms.properties
+        forms_de_DE.properties
+```
+
+## Architecture Notes (Know the Moving Parts)
+
+- Form XML is a strict server-side contract: it defines types, constraints, and errors.
+- Form instances are stored in session scope (stateful across requests) and must be cleared deliberately.
+- Client-side validation is UX; server-side validation is authoritative.
+
+For deeper context and SFRA vs SiteGenesis architectural differences, see:
+- [references/ARCHITECTURE-SGJC-SFRA.md](references/ARCHITECTURE-SGJC-SFRA.md)
+
+## Form Definition (XML)
+
+### Minimal Example
+
+Keep examples small, but always include:
+- strict types
+- max-length for strings
+- mandatory + missing-error where needed
+- parse/range errors for format/constraint enforcement
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
+    <field formid="email" type="string"
+           label="form.email.label"
+           mandatory="true"
+           max-length="254"
+           regexp="^[^@\s]+@[^@\s]+\.[^@\s]+$"
+           missing-error="form.email.required"
+           parse-error="form.email.invalid"/>
+
+    <action formid="submit" valid-form="true"/>
+</form>
+```
+
+### Reuse and Modularity
+
+Prefer `include` to avoid duplicating complex groups (e.g., an address group reused in checkout, profile, and gift registry).
+
+See the cheat sheet:
+- [references/FORM-XML-CHEATSHEET.md](references/FORM-XML-CHEATSHEET.md)
+
+## Controller Patterns
+
+### SFRA: Render Form (GET)
+
+Goals:
+- clear stale state when rendering an “empty” form
+- generate a CSRF token
+
+```javascript
+'use strict';
+
+var server = require('server');
+var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
+
+server.get('Show',
+    server.middleware.https,
+    csrfProtection.generateToken,
+    function (req, res, next) {
+        var form = server.forms.getForm('contact');
+        form.clear();
+
+        res.render('forms/contact', {
+            contactForm: form
+        });
+        next();
+    }
+);
+
+module.exports = server.exports();
+```
+
+### SFRA: Handle Submission (POST)
+
+Goals:
+- validate CSRF first
+- gate all business logic on `form.valid`
+- isolate DB writes inside `Transaction.wrap`
+- prefer `route:BeforeComplete` for persistence to keep transaction boundaries tight
+
+```javascript
+'use strict';
+
+var server = require('server');
+var Transaction = require('dw/system/Transaction');
+var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
+
+server.post('Submit',
+    server.middleware.https,
+    csrfProtection.validateRequest,
+    function (req, res, next) {
+        var form = server.forms.getForm('contact');
+
+        if (!form.valid) {
+            // SFRA base commonly provides a helper like */cartridge/scripts/formErrors.
+            // Prefer using it when available.
+            res.json({
+                success: false,
+                fieldErrors: getFormErrorsSafe(form)
+            });
+            return next();
+        }
+
+        var email = form.email.value;
+        var message = form.message && form.message.value;
+
+        this.on('route:BeforeComplete', function () {
+            Transaction.wrap(function () {
+                // Persist explicitly (no mass assignment)
+                // e.g. save a Custom Object, update profile, create a case, etc.
+                // Keep only assignments inside the transaction.
+            });
+
+            form.clear();
+        });
+
+        res.json({ success: true });
+        next();
+    }
+);
+
+function getFormErrorsSafe(form) {
+    try {
+        var formErrors = require('*/cartridge/scripts/formErrors');
+        if (formErrors && typeof formErrors.getFormErrors === 'function') {
+            return formErrors.getFormErrors(form);
+        }
+    } catch (e) {
+        // Optional dependency; fall back if not present.
+    }
+    return {};
+}
+
+module.exports = server.exports();
+```
+
+Notes:
+- Use `csrfProtection.validateAjaxRequest` if your route expects AJAX conventions.
+- Keep transactions short: no remote API calls, no heavy computation inside `Transaction.wrap`.
+
+### SiteGenesis (SGJC): Key Differences
+
+- Form is typically accessed via `app.getForm('id')` and rendered via `pdict.CurrentForms`.
+- Templates must use generated `htmlName` (SiteGenesis uses `dwfrm_` prefixes + session-specific IDs).
+- CSRF is often handled manually via `dw.web.CSRFProtection`.
+
+Use this for migration and pitfalls:
+- [references/ARCHITECTURE-SGJC-SFRA.md](references/ARCHITECTURE-SGJC-SFRA.md)
+
+## ISML Rendering Rules
+
+### Always Use Generated Field Metadata
+
+- Prefer `field.htmlName` over hardcoded names.
+- Use server-provided `pdict.csrf.*` when using SFRA CSRF middleware.
+
+Typical SFRA token:
+
+```html
+<input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}" />
+```
+
+### XSS Safety
+
+When outputting user-provided values, ensure the context is encoded (default output encoding is usually safe, but be deliberate):
+
+```html
+<isprint value="${pdict.contactForm.email.value}" encoding="htmlcontent" />
+```
+
+## Custom Validation
+
+Use custom validation for business rules that XML cannot express (uniqueness checks, cross-field constraints, etc.).
+
+Patterns:
+- Field-level: invalidate a specific field.
+- Group-level: invalidate the group for cross-field rules.
+- Form-level: invalidate the form for global errors.
+
+Keep custom validation server-side. Client-side validation is optional and must never be the security gate.
+
+## Related Skills
+
+- `sfcc-security` (CSRF, XSS, input validation)
+- `sfcc-sfra-controllers` (middleware patterns, response handling)
+- `sfcc-isml-development` (safe output encoding, template constraints)
+- `sfcc-localization` (resource bundles, locale fallback)
+
+## References
+
+- [references/FORM-XML-CHEATSHEET.md](references/FORM-XML-CHEATSHEET.md)
+- [references/ARCHITECTURE-SGJC-SFRA.md](references/ARCHITECTURE-SGJC-SFRA.md)

package/ai-instructions/skills/sfcc-forms-development/references/ARCHITECTURE-SGJC-SFRA.md

@@ -0,0 +1,143 @@
+# Advanced SFCC Forms Architecture (SiteGenesis vs SFRA)
+
+This reference is for architects and senior devs designing or migrating form flows (login, registration, checkout, account, complex configuration).
+
+## 1) Architectural Foundations
+
+The SFCC Forms Framework is not “just HTML forms.” It is a stateful, server-side framework that:
+- instantiates a form object from XML definitions
+- maintains state across requests (session-scoped)
+- enforces server-side type/constrain validation
+- supports complex multi-step flows
+
+### XML Form Definition = Server-Side Contract
+
+Form XML defines:
+- structure (fields/groups/lists)
+- parsing rules + constraints
+- resource keys (labels + errors)
+- action-level validation behavior
+
+Treat it like a schema contract between templates and controllers.
+
+## 2) Form Object Lifecycle
+
+- Form instances are stored in session scope.
+- State persists unless cleared.
+- Locale changes can invalidate/clear session form values.
+
+Operational rules:
+- Clear before rendering a “fresh” form.
+- Clear after successful submission to prevent resubmission and leakage.
+
+## 3) Validation Strategy (Defense in Depth)
+
+### Client-side validation
+
+- Purpose: UX and immediate feedback.
+- Security: none (can be bypassed).
+
+### Server-side validation
+
+- Authoritative gate.
+- Runs against XML constraints automatically.
+
+Per-field precedence (typical):
+1. parsing/type/regexp
+2. mandatory
+3. range/length bounds
+4. custom invalidation
+
+## 4) Security Architecture
+
+### CSRF
+
+Use the platform’s synchronizer token pattern correctly:
+- Generate token on form render.
+- Require token on any state-changing POST.
+
+SFRA:
+- Use CSRF middleware (`generateToken` on GET; `validateRequest` / `validateAjaxRequest` on POST).
+
+SiteGenesis:
+- Use `dw.web.CSRFProtection` explicitly (validate early, before processing).
+
+### XSS
+
+Forms are major injection vectors.
+
+Rule:
+- Always output-encode user-provided values in ISML.
+
+When rendering user data, prefer explicit encoding contexts (e.g., HTML content).
+
+### DoS / Payload abuse
+
+- Always set `max-length` on string fields.
+- Avoid expensive regex patterns.
+- Keep server-side validation and error generation efficient.
+
+## 5) Persistence and Transaction Management
+
+All writes to persistent objects must occur inside a transaction:
+- Use `dw.system.Transaction.wrap`.
+
+Guidelines:
+- Keep transactions short.
+- Do not do network calls inside transactions.
+- Map values explicitly when persisting (avoid mass assignment).
+
+### SFRA: route:BeforeComplete pattern
+
+A robust pattern is:
+- validate + decide outside the transaction
+- register persistence in `route:BeforeComplete`
+- write data inside `Transaction.wrap`
+
+This keeps the request pipeline clean and reduces accidental double-writes.
+
+## 6) SiteGenesis (SGJC) vs SFRA: Key Differences
+
+| Concern | SiteGenesis (SGJC) | SFRA |
+|---|---|---|
+| Controller model | guard-driven actions (classic) | middleware chains (`server.get/post`) |
+| Form access | `pdict.CurrentForms` / `app.getForm` | `server.forms.getForm()` |
+| Template coupling | templates can touch live session form | templates should consume serialized form data |
+| CSRF | often manual validation | middleware-driven |
+| Persistence | mixed into controller callbacks | often isolated via `route:BeforeComplete` |
+| Binding style | can be implicit/mass assignment | explicit assignment encouraged |
+
+### SiteGenesis specifics
+
+- Input names are generated and can vary (commonly `dwfrm_...`).
+- Templates must use generated names (e.g., `field.htmlName`) rather than hardcoding.
+
+## 7) Migration Checklist (SiteGenesis ➜ SFRA)
+
+1. Copy XML form definitions into the SFRA cartridge.
+2. Ensure labels/errors live in resource bundles (`templates/resources/*.properties`).
+3. Replace guard controller logic with SFRA routes.
+4. Enforce:
+   - HTTPS
+   - POST-only for state changes
+   - CSRF middleware validation
+5. Replace implicit binding with explicit mapping inside `Transaction.wrap`.
+6. Update templates to:
+   - use SFRA view model
+   - inject CSRF using `pdict.csrf.*`
+   - output-encode displayed values
+7. Clear form state at appropriate times.
+
+## 8) Secure Forms Checklist
+
+```text
+[ ] POST + HTTPS enforced
+[ ] CSRF validate before touching form data
+[ ] Server-side validation gates all writes
+[ ] Transactions are short and isolated
+[ ] Explicit mapping for writes
+[ ] max-length on strings
+[ ] Regex patterns are conservative
+[ ] Output encoding for any user data
+[ ] Clear session form state (pre-render and/or post-success)
+```

package/ai-instructions/skills/sfcc-forms-development/references/FORM-XML-CHEATSHEET.md

@@ -0,0 +1,127 @@
+# SFCC Form XML Cheat Sheet
+
+This is a practical reference for the storefront Forms Framework XML definitions found under `cartridge/forms/**`.
+
+## What the XML Controls
+
+- Form structure (fields, groups, lists)
+- Data types and parsing
+- Built-in constraint validation
+- Resource keys for labels/descriptions/errors
+- Actions (which submissions trigger full validation)
+
+## Minimum Recommended Constraints
+
+| Field Type | Must Have | Why |
+|---|---|---|
+| `string` | `max-length` | Prevent overly large payloads; reduce DoS/storage risk |
+| `string` + regexp | conservative `regexp` | Avoid ReDoS and ambiguous formats |
+| `integer` / `number` | `min`/`max` (when applicable) | Prevent negative/invalid ranges |
+| any mandatory | `missing-error` | Clear, localized feedback |
+
+## Core Elements
+
+### `<form>`
+
+```xml
+<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
+    <!-- fields / groups / lists / actions -->
+</form>
+```
+
+### `<field>`
+
+Common attributes (subset):
+
+- `formid` (required): identifier
+- `type` (required): `string`, `integer`, `number`, `boolean`, `date`
+- `label`: resource key
+- `mandatory`: `true|false`
+- `max-length` / `min-length` (strings)
+- `min` / `max` (numbers)
+- `regexp` (strings)
+- `format` (dates)
+- error keys: `missing-error`, `parse-error`, `range-error`, `value-error`
+
+Example:
+
+```xml
+<field formid="postalCode" type="string"
+       label="form.address.postal"
+       mandatory="true"
+       max-length="20"
+       regexp="^[A-Za-z0-9\-\s]{3,20}$"
+       missing-error="form.address.postal.required"
+       parse-error="form.address.postal.invalid"/>
+```
+
+### Error Key Semantics (Server-Side)
+
+When a form is submitted, constraint checks are evaluated in a predictable “first failing rule wins” manner for each field:
+
+1. Parse/type/regexp problems → `parse-error`
+2. Mandatory empty → `missing-error`
+3. Range / min/max / length bounds → `range-error`
+4. Script-triggered invalidation → `value-error` (or custom key)
+
+### `<group>`
+
+Use groups to namespace complex objects like addresses.
+
+```xml
+<group formid="shippingAddress">
+    <field formid="firstName" type="string" mandatory="true" max-length="50"/>
+    <field formid="lastName" type="string" mandatory="true" max-length="50"/>
+</group>
+```
+
+Controller access pattern:
+
+```text
+form.shippingAddress.firstName.value
+```
+
+### `<list>`
+
+Use lists for repeated groups (saved addresses, payment instruments, etc.).
+
+Guideline:
+- Treat list items as independent sub-forms with their own validity.
+- Avoid deeply nested lists; keep templates and controller logic readable.
+
+### `<action>`
+
+Actions decide whether “valid form” constraints run.
+
+```xml
+<action formid="submit" valid-form="true"/>
+<action formid="cancel" valid-form="false"/>
+```
+
+## Reuse via `<include>`
+
+Use includes to avoid repeating canonical definitions (address, phone, etc.).
+
+Pattern:
+- Create an address form definition once.
+- Include it into checkout/profile forms.
+
+This keeps validation consistent and reduces drift.
+
+## Locale-Specific Definitions
+
+If the structure truly differs by locale (not just labels), define locale-specific XML:
+
+```
+/forms/default/profile.xml
+/forms/pt_BR/profile.xml
+```
+
+The platform loads the best match for the current request locale.
+
+## Anti-Patterns
+
+- No `max-length` on string fields.
+- Aggressive, complex regex patterns (risk of catastrophic backtracking).
+- Hardcoding labels/errors instead of resource keys.
+- Depending on implicit binding/mass assignment to persist sensitive fields.