agent-docs 1.1.0 → 1.3.0

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
@@ -642,15 +642,15 @@ The plan should:
   (patch/minor/major based on the greatest change in any docs file) compared to
   the version in the latest commit in the `main` branch
 - **Document initialization of existing docs:** The existing documentation files
-  in the `docs/` directory (A4DRULES.md, APEXANNOTATIONS.md, 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.
+  in the `docs/` directory (A4DRULES.md, A4DWORKFLOWS.md, APEXANNOTATIONS.md,
+  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,
+  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

@@ -77,6 +77,7 @@ The `docs/` directory contains generated documentation files. Each doc follows a
 structured format optimized for AI agent consumption:
 
 - **[A4DRULES.md](docs/A4DRULES.md)** - Agentforce Rules Reference
+- **[A4DWORKFLOWS.md](docs/A4DWORKFLOWS.md)** - Agentforce Workflows reference
 - **[APEXANNOTATIONS.md](docs/APEXANNOTATIONS.md)** - Apex annotations reference
 - **[APEXDOC.md](docs/APEXDOC.md)** - ApexDoc documentation tool reference
 - **[CML.md](docs/CML.md)** - Constraint Modeling Language (CML) reference for
@@ -100,6 +101,9 @@ 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

@@ -0,0 +1,121 @@
+# Agentforce Workflows — Agent Guide
+
+> **Version**: 1.0.0
+
+## Overview
+
+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.
+
+---
+
+## 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 |
+
+Interface allows: view active workflows, toggle on/off, add/delete.
+
+---
+
+## Workflow Capabilities
+
+- **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
+
+---
+
+## 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 |
+
+---
+
+## Example: `salesforce-deploy.md`
+
+```text
+You have access to the `sf` terminal command. Deploy components following this process:
+
+1. **Gather Info**
+   <ask_followup_question>
+     <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**
+   sf project retrieve start --dry-run --target-org <target-org>
+   sf apex test run --code-coverage --result-format human
+   sf project deploy start --dry-run --target-org <target-org>
+
+3. **Confirm**
+   <ask_followup_question>
+     <question>Validation complete. Proceed with deployment?</question>
+     <options>["Yes, deploy now", "No, make changes first", "Show details"]</options>
+   </ask_followup_question>
+
+4. **Execute**
+   sf project deploy start --target-org <target-org>
+   sf project deploy report --target-org <target-org>
+
+5. **Post-Validation**
+   sf apex test run --target-org <target-org> --code-coverage --result-format human
+```
+
+---
+
+## SF CLI Quick Reference
+
+### Org Commands
+```bash
+sf org list                              # List authorized orgs
+sf org display --target-org <alias>      # Display org info
+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
+sf project deploy report --target-org <alias>           # Check status
+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>
+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>
+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 |

package/docs/LIGHTNINGBASECOMPONENTS.md

@@ -0,0 +1,328 @@
+# 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">
+```
+```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
+}
+```