agent-docs 1.2.0 → 1.3.1

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+pnpm format:check

package/PLAN.md

@@ -607,7 +607,7 @@ Standard MIT license with copyright holder: starch-uk
 
 - Name: `agent-docs`
 - Type: module
-- Version: `1.1.0` (current)
+- Version: `1.0.0`
 - Scripts: `format`, `format:fix`, `format:check`, `postinstall`
 - Dev dependencies: `prettier`
 - Engines: Node.js >= 20.0.0
@@ -646,11 +646,12 @@ The plan should:
   APEXDOC.md, CML.md, CODEANALYZER.md, CONTEXTDEFINITIONS.md, ESLINT.md,
   ESLINTJSDOC.md, FIELDSERVICE.md, GRAPHBINARY.md, GRAPHENGINE.md, GRAPHML.md,
   GRAPHSON.md, GREMLIN.md, GRYO.md, HUSKY.md, JEST.md, JORJE.md, JSDOC.md,
-  PMD.md, PNPM.md, PRETTIER.md, PRETTIERAPEX.md, REVENUETRANSACTIONMANAGEMENT.md,
-  TINKERPOP.md, VITEST.md, XPATH31.md) need to be initialized with version
-  `1.0.0` (or appropriate version based on their current state) when the
-  versioning system is first implemented. These existing docs will be tracked
-  going forward using the same semver system.
+  LIGHTNINGBASECOMPONENTS.md, LWCHTMLTEMPLATES.md, PMD.md, PNPM.md, PRETTIER.md,
+  PRETTIERAPEX.md, REVENUETRANSACTIONMANAGEMENT.md, TINKERPOP.md, VITEST.md,
+  XPATH31.md) need to be initialized with version `1.0.0` (or appropriate
+  version based on their current state) when the versioning system is first
+  implemented. These existing docs will be tracked going forward using the same
+  semver system.
 - Describe how scripts can help with versioning by:
     - Reading markdown files and detecting headers/sections
     - Comparing current state with the latest commit in `main` branch

package/README.md

@@ -101,6 +101,10 @@ structured format optimized for AI agent consumption:
 - **[JEST.md](docs/JEST.md)** - Jest testing framework reference
 - **[JORJE.md](docs/JORJE.md)** - Jorje Apex parser reference
 - **[JSDOC.md](docs/JSDOC.md)** - JSDoc documentation generator reference
+- **[LIGHTNINGBASECOMPONENTS.md](docs/LIGHTNINGBASECOMPONENTS.md)** - Lightning
+  Base Components reference
+- **[LWCHTMLTEMPLATES.md](docs/LWCHTMLTEMPLATES.md)** - LWC HTML Templates
+  reference
 - **[PMD.md](docs/PMD.md)** - PMD static analysis tool reference (includes Apex
   AST reference and suppressing warnings)
 - **[PNPM.md](docs/PNPM.md)** - pnpm package manager reference

package/docs/A4DWORKFLOWS.md

@@ -4,20 +4,22 @@
 
 ## Overview
 
-Workflows are reusable `.md` files defining multi-step Salesforce dev tasks. Invoke with `/[workflow-name.md]` in chat.
+Workflows are reusable `.md` files defining multi-step Salesforce dev tasks.
+Invoke with `/[workflow-name.md]` in chat.
 
-**Benefits:** Automation, consistency, error reduction, time savings, team sharing.
+**Benefits:** Automation, consistency, error reduction, time savings, team
+sharing.
 
 ---
 
 ## Creating & Managing
 
-| Action | Method |
-|--------|--------|
-| Access | Click **Rules & Workflows** (justice icon) in chat |
-| Scope | Choose **Global** or **Workspace** workflows |
-| Create | Click **+** |
-| Storage | Workspace: `.a4drules/workflows/` folder |
+| Action  | Method                                             |
+| ------- | -------------------------------------------------- |
+| Access  | Click **Rules & Workflows** (justice icon) in chat |
+| Scope   | Choose **Global** or **Workspace** workflows       |
+| Create  | Click **+**                                        |
+| Storage | Workspace: `.a4drules/workflows/` folder           |
 
 Interface allows: view active workflows, toggle on/off, add/delete.
 
@@ -25,7 +27,8 @@ Interface allows: view active workflows, toggle on/off, add/delete.
 
 ## Workflow Capabilities
 
-- **Built-in tools:** `ask_followup_question`, `read_file`, `search_files`, `new_task`
+- **Built-in tools:** `ask_followup_question`, `read_file`, `search_files`,
+  `new_task`
 - **CLI tools:** `sf` (Salesforce CLI), `git`
 - **External:** MCP tool calls
 - **Chaining:** Sequential action execution
@@ -34,13 +37,13 @@ Interface allows: view active workflows, toggle on/off, add/delete.
 
 ## Common Workflow Types
 
-| Type | Purpose |
-|------|---------|
-| Deployment | Deploy/validate components across orgs |
-| Testing | Run test suites, analyze results |
-| Release | Package, validate, deploy releases |
-| Component | Create/test/deploy Lightning components |
-| Integration | Set up/validate external integrations |
+| Type        | Purpose                                 |
+| ----------- | --------------------------------------- |
+| Deployment  | Deploy/validate components across orgs  |
+| Testing     | Run test suites, analyze results        |
+| Release     | Package, validate, deploy releases      |
+| Component   | Create/test/deploy Lightning components |
+| Integration | Set up/validate external integrations   |
 
 ---
 
@@ -54,7 +57,7 @@ You have access to the `sf` terminal command. Deploy components following this p
      <question>Which components to deploy and to which org?</question>
      <options>["Specific files/folders", "All local changes", "Specific metadata types"]</options>
    </ask_followup_question>
-   
+
    sf org display --target-org <target-org>
 
 2. **Pre-Deployment Validation**
@@ -81,6 +84,7 @@ You have access to the `sf` terminal command. Deploy components following this p
 ## SF CLI Quick Reference
 
 ### Org Commands
+
 ```bash
 sf org list                              # List authorized orgs
 sf org display --target-org <alias>      # Display org info
@@ -88,6 +92,7 @@ sf config set target-org <alias>         # Set default org
 ```
 
 ### Deployment
+
 ```bash
 sf project deploy start --target-org <alias>            # Deploy
 sf project deploy start --dry-run --target-org <alias>  # Validate only
@@ -96,6 +101,7 @@ sf project retrieve start --target-org <alias>          # Retrieve metadata
 ```
 
 ### Testing
+
 ```bash
 sf apex test run --target-org <alias> --code-coverage --result-format human
 sf apex test run --class-names "Test1,Test2" --target-org <alias>
@@ -103,6 +109,7 @@ sf apex test report --target-org <alias>
 ```
 
 ### Data
+
 ```bash
 sf data query --query "SELECT Id FROM Account LIMIT 10" --target-org <alias>
 sf data import tree --plan data/plan.json --target-org <alias>
@@ -113,9 +120,9 @@ sf data export tree --query "SELECT Id FROM Account" --target-org <alias>
 
 ## Custom Workflow Ideas
 
-| Workflow | Key Steps |
-|----------|-----------|
-| **Release** | Gather merged changes → Build changelog → Bump version → Create/validate package |
-| **New Component** | Create folder structure → Generate boilerplate files → Set up Jest tests → Deploy to dev |
-| **Integration Test** | Validate credentials → Test endpoints → Check error handling → Generate reports |
-| **Code Quality** | Run PMD analysis → Check accessibility → Validate naming → Generate reports |
+| Workflow             | Key Steps                                                                                |
+| -------------------- | ---------------------------------------------------------------------------------------- |
+| **Release**          | Gather merged changes → Build changelog → Bump version → Create/validate package         |
+| **New Component**    | Create folder structure → Generate boilerplate files → Set up Jest tests → Deploy to dev |
+| **Integration Test** | Validate credentials → Test endpoints → Check error handling → Generate reports          |
+| **Code Quality**     | Run PMD analysis → Check accessibility → Validate naming → Generate reports              |

package/docs/LIGHTNINGBASECOMPONENTS.md

@@ -0,0 +1,485 @@
+# Lightning Base Components
+
+> **Version**: 1.0.0
+
+## Guidelines
+
+- Prefer base components over custom HTML - built-in SLDS, a11y, less
+  maintenance
+- A11y: Always provide accessible names via `label`, `aria-label`,
+  `alternative-text`
+- Events: `onclick` (buttons), `onchange`/`onselect` (inputs/menus),
+  `onstatuschange` (flows), `onuploadfinished` (files), `onscan`/`onerror`
+  (barcode)
+- Nav: Use `lightning/navigation` not `href`
+- Style: SLDS utilities + `--slds-c-*` CSS vars. Avoid internal overrides
+- Files: Guest uploads via org prefs. `file-field-name`/`value` for guests,
+  `record-id` for auth users
+- Limits: combobox no multi-select/autocomplete; barcode/click-to-dial no
+  iFrames; carousel max 6 images; flow restrictions on LWR+custom components
+
+## ValidityState & Validation
+
+**ValidityState props** (all boolean): `valid`, `valueMissing`, `typeMismatch`,
+`patternMismatch`, `tooLong`, `tooShort`, `rangeOverflow`, `rangeUnderflow`,
+`stepMismatch`, `badInput`, `customError`
+
+**Methods**: `setCustomValidity(msg)`, `reportValidity()`, `checkValidity()`
+
+**Custom messages**: `message-when-value-missing`, `message-when-type-mismatch`,
+`message-when-pattern-mismatch`, `message-when-too-long`,
+`message-when-too-short`, `message-when-range-overflow`,
+`message-when-range-underflow`, `message-when-step-mismatch`,
+`message-when-bad-input`
+
+Start w/ LDS components for built-in validation. Client+server validation
+together.
+
+## Components
+
+**Legend**: `*` = required, `|` = options, `→` = returns
+
+### lightning-accordion-section
+
+Nest in `lightning-accordion`
+
+- `class`, `heading-level` (1-6), `label`, `name`\*
+- Slots: default, `actions`
+- ARIA: `role="listitem"`, `aria-expanded`, `aria-controls`
+- Event: `onactive`
+
+### lightning-alert (lightning/alert)
+
+`LightningAlert.open(config)` → Promise
+
+- `label`, `message`\*, `theme`
+  (default|shade|inverse|alt-inverse|success|info|warning|error|offline),
+  `variant` (header|headerless)
+- ARIA: `role="alertdialog"`, focus trap
+
+### lightning-avatar
+
+- `alternative-text`\* (if informational), `class`, `fallback-icon-name`
+  (standard/custom only), `initials`, `src`, `variant` (circle|square)
+- Initials+fallback: initials show w/ icon bg color
+
+### lightning-badge
+
+- `class`, `icon-name`, `icon-position` (end|start), `label`
+- No links/nested elements. Use `slds-theme_*` for colors
+
+### lightning-barcode-scanner
+
+Mobile only, no iFrames
+
+- `disabled`, `disabled-alternative-text`, `disabled-icon-src`,
+  `enable-continuous-scan`, `enabled-alternative-text`, `enabled-icon-src`,
+  `icon-size`
+- Events: `onerror`, `onscan` → `event.detail.scannedBarcodes`
+
+### lightning-breadcrumb
+
+Nest in `lightning-breadcrumbs`
+
+- `class`, `href` (defaults "#"), `label`\*, `name`
+- Event: `onclick` (use w/ lightning/navigation)
+
+### lightning-breadcrumbs
+
+- `class`
+- Slots: `lightning-breadcrumb`
+- ARIA: `role="navigation"`, last item `aria-current="page"`
+
+### lightning-button
+
+- `accesskey`, `aria-atomic`, `aria-controls`, `aria-describedby`,
+  `aria-expanded`, `aria-haspopup`, `aria-label`, `aria-labelledby`,
+  `aria-live`, `class`, `disabled`, `disable-animation`, `icon-name` (utility),
+  `icon-position` (end|start), `label`\*, `stretch`, `tabindex`, `title`, `type`
+  (button|reset|submit), `variant`
+  (base|brand|brand-outline|destructive|destructive-text|inverse|neutral|success)
+- Event: `onclick`
+- Use button-icon for icon-only. Min 44x44px mobile
+
+### lightning-button-group
+
+- `class`
+- Slots: `lightning-button*`
+
+### lightning-button-icon-stateful
+
+- `accesskey`, `alternative-text`, `aria-atomic`, `aria-controls`,
+  `aria-describedby`, `aria-expanded`, `aria-haspopup`, `aria-label`_,
+  `aria-live`, `class`, `disabled`, `icon-name`_ (utility), `selected`, `size`,
+  `variant` (border|border-filled|border-inverse)
+- ARIA: `aria-pressed`
+- Event: `onclick`
+
+### lightning-button-menu
+
+- `alternative-text`, `class`, `disabled`, `icon-name`, `icon-size`, `is-draft`,
+  `draft-alternative-text`, `is-loading`, `loading-state-alternative-text`,
+  `label`, `menu-alignment`, `size`, `tooltip`, `title`, `variant`
+  (bare|bare-inverse|border|border-filled|border-inverse|container)
+- Slots: `lightning-menu-item`, `lightning-menu-divider`,
+  `lightning-menu-subheader`
+- ARIA: `aria-haspopup="true"`, `aria-expanded`
+- Events: `onclose`, `onopen`, `onselect`
+
+### lightning-button-stateful
+
+- `accesskey`, `aria-*` (same as button), `class`, `disabled`, `icon-name`
+  (utility), `label-when-hover`, `label-when-off`, `label-when-on`, `selected`,
+  `tabindex`, `variant` (brand|destructive|inverse|neutral|success|text)
+- ARIA: `aria-pressed`, `aria-live="polite"`
+- Event: `onclick` (toggle selected)
+
+### lightning-card
+
+- `class`, `icon-name`, `title`
+- Slots: `actions`, `footer`, `title`, default
+
+### lightning-carousel
+
+Max 6 images
+
+- `class`, `disable-auto-refresh`, `disable-auto-scroll`, `scroll-duration`
+- Slots: `lightning-carousel-image`
+- ARIA: indicators `role="tablist"`
+
+### lightning-carousel-image
+
+- `alternative-text`, `description`, `header`, `href`, `src`\*
+
+### lightning-click-to-dial
+
+Lightning Experience only, no iFrames. Requires Open CTI `enableClickToDial`
+
+- `record-id`, `value` (phone)
+- Event: `onclicktodial`
+
+### lightning-combobox
+
+No multi-select/autocomplete. Mobile issues - consider HTML `<select>`
+
+- `autocomplete`, `class`, `label`_, `message-when-value-missing`, `options`_
+  [{value,label,description?}], `required`, `validity`, `value`, `variant`
+  (label-hidden)
+- Events: `onchange` → `event.detail.selectedValue`, `onopen`
+
+### lightning-dynamic-icon
+
+- `alternative-text` (provide on small screens), `type`\*
+  (ellie|eq|score|strength|trend|waffle)
+
+### lightning-file-upload
+
+Max 25 files, 2GB each. Guest: create `*fileupload__c` field
+
+- `accept`, `class`, `file-field-name`, `file-field-value`, `label`, `record-id`
+- Event: `onuploadfinished` → `event.detail.files` [{name,documentId}]
+
+### lightning-flow
+
+Custom components unsupported on LWR
+
+- `flow-api-name`\*, `flow-input-variables`, `flow-finish-behavior`
+  (NONE|RESTART)
+- Event: `onstatuschange` → status, outputVariables
+
+### lightning-formatted-address
+
+Format by user locale. Links Google Maps
+
+- `city`, `country`, `disabled`, `latitude`, `longitude`, `postal-code`,
+  `province`, `show-static-map`, `street`, `variant` (plain)
+
+### lightning-formatted-email
+
+- `bcc`, `body`, `cc`, `disable-linkify`, `hide-icon`, `label`, `subject`,
+  `value`
+
+### lightning-formatted-location
+
+- `latitude`_, `longitude`_
+
+### lightning-formatted-number
+
+User locale
+
+- `currency-code`, `currency-display-as` (code|name|symbol), `format-style`
+  (currency|decimal|percent|percent-fixed), `maximum-fraction-digits`,
+  `maximum-significant-digits`, `minimum-fraction-digits`,
+  `minimum-significant-digits`, `value`\*
+
+### lightning-formatted-rich-text
+
+- `disable-linkify`, `value`
+- Supported: a, div, p, h1-h6, strong, em, ul, ol, li, table, img, etc.
+
+### lightning-formatted-time
+
+- `value`\* (ISO8601)
+
+### lightning-input
+
+- `accept`, `aria-describedby`, `aria-labelledby`, `autocomplete`, `checked`,
+  `class`, `date-aria-describedby`, `date-aria-labelledby`, `disabled`,
+  `field-level-help`, `files`, `label`_, `max`, `maxlength`,
+  `message-when-_`(all validation msgs),`min`, `minlength`, `multiple`, `name`, `pattern`, `placeholder`, `readonly`, `required`, `step`, `time-aria-describedby`, `time-aria-labelledby`, `type`(checkbox|checkbox-button|color|date|datetime|datetime-local|email|file|number|password|search|tel|text|time|toggle|url),`validity`, `value`, `variant`
+  (label-hidden|label-inline|label-stacked|standard)
+- Events: `onblur`, `onchange`, `onfocus`, `oninput`
+
+### lightning-input-field
+
+- `field-name`\*, `required`, `value`, `variant`
+- Event: `onchange`
+
+### lightning-input-location
+
+Validates lat -90/90, lon -180/180
+
+- `city`, `country`, `latitude`, `longitude`, `postal-code`, `province`,
+  `street`
+- Event: `onchange` → lat, lon
+
+### lightning-layout-item
+
+- `flexibility`, `large-device-size` (1-12), `medium-device-size`, `padding`,
+  `size`, `small-device-size`
+
+### lightning-map
+
+- `center`, `list-view`, `map-markers`\*, `markers-title`,
+  `show-footer-address`, `zoom-level`
+
+### lightning-menu-divider
+
+- `variant` (compact|default)
+
+### lightning-menu-item
+
+- `accesskey`, `checked`, `class`, `draft-alternative-text`, `href`,
+  `icon-name`, `icon-type` (color|standard), `is-draft`, `label`,
+  `prefix-icon-name`, `tabindex`, `target`, `value`
+- Selection via parent `onselect`
+
+### lightning-menu-subheader
+
+- `label`\*
+
+### lightning-modal (lightning/modal)
+
+Extend `LightningModal`
+
+- `description`, `disableClose`, `label`\*, `size` (full|large|medium|small)
+- ARIA: focus trap
+- Events bubble to opener
+
+### lightning-modal-body/footer
+
+Slots: default
+
+### lightning-modal-header
+
+- `icon-assistive-text`, `icon-name`, `label`\*
+
+### lightning-omnistudio-flexcard
+
+- `flexcard-name`\*, `input`, `record-id`
+
+### lightning-omnistudio-omniscript
+
+- `input`, `record-id`, `script-name`\*
+
+### lightning-output-field
+
+- `field-name`\*, `record-id`, `variant` (label-hidden|standard)
+
+### lightning-pill
+
+3 clickable areas: icon/avatar, label, remove btn
+
+- `class`, `has-error`, `href`, `label`, `name`, `variant` (link|plain)
+- Slots: default (icon/avatar)
+- Events: `onclick`, `onremove`
+
+### lightning-pill-container
+
+- `class`, `is-collapsible`, `is-expanded`, `items`\*, `single-line`, `variant`
+  (bare|standard)
+- Event: `onitemremove` → item, index
+
+### lightning-progress-bar
+
+- `size` (large|medium|small|x-large), `value`\* (0-100), `variant`
+  (circular|circular-with-label|light)
+
+### lightning-progress-indicator
+
+- `class`, `current-step`, `type` (horizontal|vertical), `variant` (base|path)
+- Slots: `lightning-progress-step`
+
+### lightning-progress-ring
+
+- `direction` (clockwise|counterclockwise), `value`\* (0-100), `variant`
+  (active-step|base|base-autocomplete|expired|warning)
+
+### lightning-prompt (lightning/prompt)
+
+`LightningPrompt.open()` → Promise
+
+- `defaultValue`, `label`\*, `message`, `options`, `variant` (header|headerless)
+
+### lightning-quick-action-panel
+
+- `object-api-name`_, `quick-action-api-name`, `record-id`_
+- Event: `onquickactionmenu`
+
+### lightning-record-edit-form
+
+Uses LDS. Shows first validation error
+
+- `class`, `layout-type` (Compact|Full), `mode` (edit|readonly),
+  `object-api-name`, `record-id`
+- Events: `onerror`, `onload`, `onsubmit`, `onsuccess`
+
+### lightning-relative-date-time
+
+- `class`, `options`, `value`\*
+
+### lightning-rich-text-toolbar-button
+
+- `class`, `disabled`, `icon-name`, `pressed`, `value`
+
+### lightning-rich-text-toolbar-button-group
+
+Slots: `lightning-rich-text-toolbar-button`
+
+### lightning-select
+
+- `class`, `disabled`, `field-level-help`, `label`\*,
+  `message-when-value-missing`, `multiple`, `options` [{value,label,disabled?}],
+  `required`, `size`, `validity`, `value`, `variant`
+- Event: `onchange` → `event.detail.value`
+
+### lightning-slider
+
+Use onchange not onblur (Safari). Values clamped to min/max
+
+- `class`, `disabled`, `label`, `max` (100), `min` (0), `step`, `type`
+  (horizontal|vertical), `value`
+- Event: `onchange`
+
+### lightning-spinner
+
+- `variant` (brand|inverse|default)
+- Use w/ `if:true`
+
+### lightning-tab
+
+Lazy loaded. Only query active/prev-active content
+
+- `class`, `end-icon-alternative-text`, `end-icon-name`, `icon-assistive-text`,
+  `icon-name`, `label`\*, `show-error-indicator`
+- Event: `onactive`
+
+### lightning-textarea
+
+- `aria-describedby`, `aria-labelledby`, `autocomplete`, `class`, `disabled`,
+  `label`_, `maxlength`,
+  `message-when-_`, `minlength`, `placeholder`, `read-only`, `required`, `validity`, `value`, `variant`
+- Events: `onblur`, `onchange`, `onfocus`
+
+### lightning-tile
+
+- `class`, `label`\*
+- Slots: `media`, default
+- Event: `onactiontriggered`
+
+### lightning-toast (lightning/toast)
+
+`Toast.show()` → Promise
+
+- `label`\*, `labelLinks`, `message`, `messageLinks`, `mode`
+  (dismissible|sticky), `variant` (error|info|success|warning)
+
+### lightning-toast-container (lightning/toastContainer)
+
+One per page. Ctrl+F6/Cmd+F6 nav
+
+- `containerPosition` (absolute|fixed), `maxToasts` (3), `toastPosition`
+  (bottom-center|bottom-left|bottom-right|top-center|top-left|top-right)
+
+### lightning-tree
+
+- `class`, `header`, `items`\*
+- Event: `onselect` → name
+
+### lightning-tree-grid
+
+Set `sortable:true` on columns for sorting
+
+- `class`, `columns`_, `data`, `expanded-rows`, `hide-checkbox-column`,
+  `key-field`_, `max-column-width`, `min-column-width`,
+  `resize-column-disabled`, `selected-rows`, `show-row-number-column`, `variant`
+- Events: `onrowaction`, `onrowselection`, `onsort`
+
+### lightning-vertical-navigation
+
+- `class`, `selected-item`
+- Slots: `lightning-vertical-navigation-item*`
+- Events: `onbeforeselect`, `onselect`
+
+### lightning-vertical-navigation-item
+
+- `badge`, `class`, `href`, `icon-name`, `label`\*, `name`
+- Event: `onselect`
+
+### lightning-vertical-navigation-item-badge
+
+- `class`, `label`, `variant` (default|inverse|lightest)
+
+### lightning-vertical-navigation-item-icon
+
+- `alternative-text`, `class`, `icon-name`, `position` (end|start)
+
+## Patterns
+
+### Validation
+
+```js
+// Check validity
+if (!this.template.querySelector('lightning-input').checkValidity()) {
+	this.template.querySelector('lightning-input').reportValidity();
+}
+```
+
+### Styling
+
+```html
+<lightning-button class="slds-m-left_small"></lightning-button>
+```
+
+```css
+--slds-c-button-color-background
+--slds-c-button-text-color
+```
+
+### Navigation
+
+```js
+import { NavigationMixin } from 'lightning/navigation';
+this[NavigationMixin.Navigate]({
+	type: 'standard__recordPage',
+	attributes: { recordId, actionName: 'view' },
+});
+```
+
+### Events
+
+```js
+handleChange(event) {
+  const value = event.detail.value; // or .selectedValue
+}
+```