agent-docs 1.0.1 → 1.1.0

package/PLAN.md

@@ -11,8 +11,8 @@ AI agent instruction documents ("docs") for AI-enabled IDEs.
 - **Primary contents**: Markdown documentation in `docs/`
 - **Code formatting**: Prettier (via `pnpm format` / `pnpm format:check`)
 - **CI**: GitHub Actions workflow that runs `pnpm format:check` on push/PR
-- **Postinstall script**: `postinstall.mjs` that creates symlinks/junctions to
-  `docs/` in consuming projects
+- **Postinstall script**: `postinstall.mjs` that copies the `docs/` directory to
+  consuming projects if they don't already have one
 - **AI Agent Guidance**: `.cursor/plans/` contains structured workflows and
   instructions for AI coding assistants
 - **IDE Rules**: `.cursor/rules/` contains agent rules for Cursor IDE
@@ -52,19 +52,15 @@ The README.md should contain:
         - When `agent-docs` is installed into another project, a `postinstall`
           script will run in the consuming project.
         - If the consuming project does **not** already have a `docs/`
-          directory, the script will create a single symlink/junction from the
-          consuming project's `docs/` directory to this package's `docs/`
-          directory:
-            - On Unix/macOS, a directory symlink is created
-            - On Windows, a junction is created
+          directory, the script will copy this package's `docs/` directory to
+          the consuming project's root directory.
         - If the consuming project **already has** a `docs/` directory, the
-          script does nothing and you can instead manage your own docs layout.
-    - Optional manual instructions for symlinking (Unix/macOS) or junction
-      linking (Windows) if you prefer not to rely on `postinstall`, or need a
-      custom layout:
-        - Individual files from the `docs/` folder to the root of the actual
-          project, OR
-        - The entire `docs` folder to the root of the actual project
+          script does nothing, and your existing docs layout is left unchanged.
+    - Optional manual instructions for copying files if you prefer not to rely
+      on `postinstall`, or need a custom layout:
+        - Copy individual files from the `docs/` folder to the root of the
+          actual project, OR
+        - Copy the entire `docs` folder to the root of the actual project
     - Explanation of how to update IDE agent rules (e.g., Cursor's
       `.cursor/rules/` or similar) to reference the linked docs using
       `@filename` syntax or relative paths, so the AI agent can access the
@@ -369,13 +365,14 @@ Add any other context, examples, or screenshots about the feature request here.
 ### `postinstall.mjs`
 
 The postinstall script that runs when this package is installed in another
-project. It should copy this package's `docs/` directory to the consuming
-project's root directory, but only if the consuming project doesn't already have
-a `docs/` directory.
+project. It copies this package's `docs/` directory to the consuming project's
+root directory, but only if the consuming project doesn't already have a `docs/`
+directory. The script uses file copying instead of symlinks/junctions for better
+cross-platform reliability.
 
 ```js
 // postinstall.mjs
-// Implementation details for creating cross-platform symlinks/junctions
+// Implementation details for copying docs directory cross-platform
 ```
 
 ### `prettier.config.js`
@@ -610,7 +607,7 @@ Standard MIT license with copyright holder: starch-uk
 
 - Name: `agent-docs`
 - Type: module
-- Version: `1.0.0`
+- Version: `1.1.0` (current)
 - Scripts: `format`, `format:fix`, `format:check`, `postinstall`
 - Dev dependencies: `prettier`
 - Engines: Node.js >= 20.0.0
@@ -640,20 +637,20 @@ The plan should:
     - **Major version bump** - Sections replaced or removed from a file compared
       to the version in the latest commit in the `main` branch
 - Document that the project as a whole maintains a version in `package.json`
-  (currently `1.0.0`)
+  (currently `1.1.0`)
 - Explain that changes to docs files should increment the project version
   (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 (APEXANNOTATIONS.md, APEXDOC.md, CODEANALYZER.md,
-  CPD.md, ESLINT.md, ESLINTJSDOC.md, FLOWSCANNER.md, GRAPHBINARY.md,
-  GRAPHENGINE.md, GRAPHML.md, GRAPHSON.md, GREMLIN.md, GRYO.md, HUSKY.md,
-  JEST30.md, JORJE.md, JSDOC.md, PMD.md, PMDAPEXAST.md, PMDSUPPRESSWARNINGS.md,
-  PNPM.md, PRETTIER.md, PRETTIERAPEX.md, REGEX.md, RETIREJS.md, SFCLI.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, 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.
 - 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

@@ -76,6 +76,7 @@ with any technology.
 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
 - **[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
@@ -109,10 +110,58 @@ structured format optimized for AI agent consumption:
 - **[TINKERPOP.md](docs/TINKERPOP.md)** - Apache TinkerPop graph computing
   framework reference
 - **[VITEST.md](docs/VITEST.md)** - Vitest testing framework reference
-- **[CODEANALYZER.md#vs-code-integration](docs/CODEANALYZER.md#vs-code-integration)** -
-  VS Code editor integration
 - **[XPATH31.md](docs/XPATH31.md)** - XPath 3.1 query language reference
 
+## Usage
+
+### Creating and Maintaining Docs
+
+To create new documentation files:
+
+1. **Create a new markdown file** in the `docs/` directory following the naming
+   convention:
+    - Uppercase, no spaces, no dots
+    - Version numbers become part of the name (e.g., "XPath 3.1" → `XPATH31.md`)
+    - Remove redundant words like "plugin" when they appear between other words
+      (e.g., "prettier-plugin-apex" → `PRETTIERAPEX.md`)
+
+2. **Follow the structured format** optimized for AI agent consumption:
+    - Overview section with brief context
+    - Core Concepts / Key Features (bulleted lists)
+    - Configuration / Setup (tables when possible)
+    - Usage / Examples (minimal, essential code only)
+    - API Reference (condensed, often in tables)
+    - Patterns & Best Practices
+    - Important Notes (critical gotchas, limitations)
+
+3. **Apply optimization guidelines**:
+    - Keep token count low - be terse but precise
+    - Use bullet points over prose for scannability
+    - Prefer tables for structured data (config options, APIs, properties)
+    - Include code snippets only when essential
+    - Cross-reference related docs using `[Name](FILENAME.md)` format
+    - Include a document in a prompt or rule with @FILENAME.md
+
+### AI Agent Guidance
+
+This repository includes AI Agent Guidance files in `.cursor/plans/` that
+provide structured instructions and workflows for AI coding assistants (like
+Cursor's Agent). These plan files document processes, best practices, and
+step-by-step workflows for various tasks, making them accessible to AI agents
+through the `.cursor/plans/` directory structure.
+
+When AI agents need guidance on how to perform specific tasks or follow certain
+workflows, they can reference these plan files to understand the expected
+process and provide accurate assistance. Key plan files include:
+
+- **VERSIONING.md** - Semantic versioning rules and workflows for documentation
+  files
+- **OPTIMISE.md** - Strategies and best practices for maintaining low token
+  counts and efficient documentation formats
+
+These plans are used by AI-powered IDEs to optimize docs and maintain
+consistency across the documentation set.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this

package/docs/A4DRULES.md

@@ -0,0 +1,145 @@
+# Agentforce Rules Reference
+
+> **Version**: 1.0.0
+
+Purpose
+
+- Provide persistent system‑level guidance Agentforce follows during Salesforce
+  development.
+- Enforce coding, metadata, org and team conventions across sessions.
+
+Key concepts
+
+- Rules are persistent instructions that influence Agentforce behavior.
+- Two scopes:
+    - Global — companywide standards applied to all projects.
+    - Workspace — project/org specific; stored in the project’s .a4drules
+      folder.
+- Out‑of‑the‑box global rules exist and can be toggled; shipped rules may be
+  overwritten by extension updates.
+
+Where to manage
+
+- Open Rules & Workflows (justice icon) in Agentforce chat.
+- Create: click + in Rules tab or use `/newrule` in chat.
+- Popover UI: view active rules, enable/disable, add, delete.
+- Workspace rules: project/.a4drules. Global rules: OS‑dependent location.
+
+Minimal file template (low‑token)
+
+```text
+# Rule: [Name]
+
+Description: [one-line purpose]
+
+Applies to: `[file pattern]`
+
+Guidelines:
+- [short guideline 1]
+- [short guideline 2]
+```
+
+Rule design patterns
+
+- Scope: choose Global for org‑wide policies (naming, security) or Workspace for
+  repo/org specifics.
+- One file type per rule when possible to reduce ambiguity.
+- Keep guidelines short, precise, and actionable (3–6 lines is ideal).
+- Version‑gate rules for fields/features that require a minimum API version.
+
+Validation checklist pattern (use inside rules)
+
+- File suffix & location (e.g., `folder/*.ext`, include generated meta filenames
+  like `*.ext-meta.xml`).
+- Required fields present and follow naming/format rules.
+- Mutually exclusive fields: only one of a defined set is present.
+- Enumerations: value belongs to allowed list.
+- Numeric fields: in allowed range and type (int/float).
+- Cross‑field constraints (e.g., boolean toggle requires another field match).
+- API version: ensure package API supports any fields used.
+- Manifest behavior: wildcard support and retrieval side effects.
+
+Common guideline examples (generic)
+
+- File naming & location
+    - Suffix must match the metadata type (e.g., `.ext` and optionally
+      `.ext-meta.xml`) and files stored in the corresponding folder.
+
+- Identity / fullName rules
+    - fullName must use only letters, numbers and underscores; start with a
+      letter; no spaces; not end with `_`; not contain `__`; unique within
+      package.
+
+- Exclusive content fields
+    - Exactly one of [fieldA, fieldB, fieldC, fieldD] may be set. Enforce count
+      == 1.
+
+- Required / conditional fields
+    - FieldX is required.
+    - If FieldY = true then FieldZ must equal the related resource name.
+    - If FieldType ∈ {type1, type2} then NumericHeight must be present and > 0.
+
+- Enumerations & presets
+    - Validate enumerated fields against the allowed list (store the list
+      centrally in the rule).
+
+- API gating
+    - Only allow fields introduced in API ≥ N when package.xml version >= N.
+
+- Manifest & retrieval
+    - Support for wildcard (\*) in package.xml — note older API versions may
+      behave differently.
+    - Retrieving a component can cause related Profile/PermissionSet entries to
+      include references; warn about side effects.
+
+Example minimal templates
+
+- Generic metadata file template
+
+```xml
+<MetadataType xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>MyResource</fullName>
+  <requiredField>value</requiredField>
+  <optionalField>value</optionalField>
+</MetadataType>
+```
+
+- Example rule pseudocode checks
+
+```text
+# Rule: SingleContentField
+
+Description: Ensure exactly one content source is defined.
+
+Applies to: `**/*.ext`
+
+Guidelines:
+- Count([fieldA, fieldB, fieldC, fieldD]) == 1
+- If fieldC set -> ensure frameHeight is present and integer > 0
+- Package API version must be >= 14 when using iconField
+```
+
+Best practices
+
+- Make rules atomic and single‑purpose to simplify enforcement and debugging.
+- Prefer short lines and plain tokens to keep rules compact for AI processing.
+- Store enumerations centrally to avoid duplication and speed validation.
+- Version‑gate rules for fields that depend on API releases.
+- Test rule behavior by toggling and running typical retrieve/deploy scenarios.
+- Review and update rules whenever package/API versions or team conventions
+  change.
+
+Rule lifecycle checklist
+
+- Create: Name + one-line Description + Applies pattern.
+- Add 3–6 precise Guidelines (format/validators/version gates).
+- Save to workspace .a4drules or global rules UI.
+- Enable and test with representative metadata files and package.xml.
+
+Usage notes for agents
+
+- Apply rules as filters during generation and validation steps.
+- Prefer minimal, deterministic responses based on active rules.
+- When multiple rules conflict, enforce Global rules last modified earlier than
+  Workspace (or use a defined precedence ordering).
+- Emit succinct validation errors with line/field hints to aid quick fixes.

package/docs/REVENUETRANSACTIONMANAGEMENT.md

@@ -1,6 +1,6 @@
 # Salesforce Revenue Cloud: Transaction Management
 
-> v1.0.0 | Editions: Enterprise, Unlimited, Developer (Lightning Experience)
+> v1.0.2 | Editions: Enterprise, Unlimited, Developer (Lightning Experience)
 
 ## Quick Reference
 
@@ -106,12 +106,14 @@ configuration.
 | `RecordResource`                 | Create record object from sales transaction field values                                         |
 | `RecordWithReferenceRequest`     | Associate record object with reference identifier                                                |
 
-**ConfigurationOptionsInput Properties:** | Property | Type | Description |
-|----------|------|-------------| | `addDefaultConfiguration` | Boolean |
-Auto-add default configuration (bundle/product attributes) | |
-`executeConfigurationRules` | Boolean | Require adherence to configuration rules
-| | `validateAmendRenewCancel` | Boolean | Run amend/renew/cancel validations |
-| `validateProductCatalog` | Boolean | Validate against product catalog |
+**ConfigurationOptionsInput Properties:**
+
+| Property                    | Type    | Description                                                |
+| --------------------------- | ------- | ---------------------------------------------------------- |
+| `addDefaultConfiguration`   | Boolean | Auto-add default configuration (bundle/product attributes) |
+| `executeConfigurationRules` | Boolean | Require adherence to configuration rules                   |
+| `validateAmendRenewCancel`  | Boolean | Run amend/renew/cancel validations                         |
+| `validateProductCatalog`    | Boolean | Validate against product catalog                           |
 
 **PlaceSalesTransactionExecutor.execute() Parameters:**
 
@@ -124,34 +126,39 @@ Auto-add default configuration (bundle/product attributes) | |
 - `catalogRatesPreferenceEnum` (CatalogRatesPreferenceEnum) — Rate card entries
   preference (optional)
 
-**Enums:** | Enum | Values | Description | |------|--------|-------------| |
-`CatalogRatesPreferenceEnum` | `Fetch`, `Skip` | Rate card entries for
-usage-based selling | | `ConfigurationExecutionEnum` | `RunAndAllowErrors`,
-`RunAndBlockErrors`, `Skip` | Configuration execution mode | |
-`PricingPreferenceEnum` | `Force`, `Skip`, `System` | Pricing preference during
-transaction |
+**Enums:**
+
+| Enum                         | Values                                           | Description                               |
+| ---------------------------- | ------------------------------------------------ | ----------------------------------------- |
+| `CatalogRatesPreferenceEnum` | `Fetch`, `Skip`                                  | Rate card entries for usage-based selling |
+| `ConfigurationExecutionEnum` | `RunAndAllowErrors`, `RunAndBlockErrors`, `Skip` | Configuration execution mode              |
+| `PricingPreferenceEnum`      | `Force`, `Skip`, `System`                        | Pricing preference during transaction     |
 
 ### CommerceTax
 
 Manages communication between Salesforce and external tax engines.
 
-**Classes:** | Class | Purpose | |-------|---------| | `AddressesResponse` |
-Ship To, Ship From, Sold To address responses | | `AmountDetailsResponse` | Tax
-amount, total with tax, exempt amount | | `CustomTaxAttributesResponse` |
-Additional custom tax attributes | | `DocumentCodeRequest` | Document code for
-tax calculation | | `ExemptDetailsResponse` | Exemption ID, number, reason | |
-`ImpositionResponse` | Tax imposition details (id, name, type, subType) | |
-`JurisdictionResponse` | Tax jurisdiction (country, region, state, level) | |
-`LineItemResponse` | Line item tax calculation results | |
-`LineTaxAddressesRequest` | Per-line-item addresses for tax calculation | |
-`RuleDetailsResponse` | Tax rules used (nonTaxableRuleId, rateRuleId,
-rateSourceId) | | `TaxAddressesRequest` | Ship From/To, Sold To, Bill To
-addresses | | `TaxAddressRequest` | Address details (city, country, state,
-postalCode, lat/long) | | `TaxApiException` | Tax calculation exceptions | |
-`TaxCustomerDetailsRequest` | Customer details (accountId, code,
-exemptionNo/Reason) | | `TaxDetailsResponse` | Tax calculation details per line
-| | `TaxEngineRequest` | Tax engine request payload | | `TaxEngineResponse` |
-Tax engine response |
+**Classes:**
+
+| Class                         | Purpose                                                      |
+| ----------------------------- | ------------------------------------------------------------ |
+| `AddressesResponse`           | Ship To, Ship From, Sold To address responses                |
+| `AmountDetailsResponse`       | Tax amount, total with tax, exempt amount                    |
+| `CustomTaxAttributesResponse` | Additional custom tax attributes                             |
+| `DocumentCodeRequest`         | Document code for tax calculation                            |
+| `ExemptDetailsResponse`       | Exemption ID, number, reason                                 |
+| `ImpositionResponse`          | Tax imposition details (id, name, type, subType)             |
+| `JurisdictionResponse`        | Tax jurisdiction (country, region, state, level)             |
+| `LineItemResponse`            | Line item tax calculation results                            |
+| `LineTaxAddressesRequest`     | Per-line-item addresses for tax calculation                  |
+| `RuleDetailsResponse`         | Tax rules used (nonTaxableRuleId, rateRuleId, rateSourceId)  |
+| `TaxAddressesRequest`         | Ship From/To, Sold To, Bill To addresses                     |
+| `TaxAddressRequest`           | Address details (city, country, state, postalCode, lat/long) |
+| `TaxApiException`             | Tax calculation exceptions                                   |
+| `TaxCustomerDetailsRequest`   | Customer details (accountId, code, exemptionNo/Reason)       |
+| `TaxDetailsResponse`          | Tax calculation details per line                             |
+| `TaxEngineRequest`            | Tax engine request payload                                   |
+| `TaxEngineResponse`           | Tax engine response                                          |
 
 **TaxAddressRequest Properties:** `city`, `country`, `countryCode`, `latitude`,
 `locationCode`, `longitude`, `postalCode`, `state`, `stateCode`, `street`
@@ -169,10 +176,13 @@ Tax engine response |
 - `RecordResource` — Create record from quote field values
 - `RecordWithReferenceRequest` — Associate record with reference ID
 
-**Enums:** | Enum | Values | |------|--------| | `CatalogRatesPreferenceEnum` |
-`Fetch`, `Skip` | | `ConfigurationInputEnum` | `RunAndAllowErrors`,
-`RunAndBlockErrors`, `Skip` | | `PricingPreferenceEnum` | `Force`, `Skip`,
-`System` |
+**Enums:**
+
+| Enum                         | Values                                           |
+| ---------------------------- | ------------------------------------------------ |
+| `CatalogRatesPreferenceEnum` | `Fetch`, `Skip`                                  |
+| `ConfigurationInputEnum`     | `RunAndAllowErrors`, `RunAndBlockErrors`, `Skip` |
+| `PricingPreferenceEnum`      | `Force`, `Skip`, `System`                        |
 
 ---
 
@@ -559,13 +569,17 @@ Contains information about asset create/update from
 **Important:** Included in `CreateAssetOrderEvent` message; cannot subscribe
 directly.
 
-**Fields:** | Field | Type | Description | |-------|------|-------------| |
-`AssetId` | Reference | Created/updated asset ID (nillable) | | `ErrorCode` |
-String | Error type reference code (nillable) | | `ErrorMessage` | String |
-Error information (nillable) | | `EventUuid` | String | Platform event message
-UUID (nillable) | | `IsSuccess` | Boolean | Request success status (default:
-false, v61.0+) | | `OrderItemId` | Reference | Order item ID used in request
-(v61.0+) | | `ReplayId` | String | Event stream position (nillable) |
+**Fields:**
+
+| Field          | Type      | Description                                     |
+| -------------- | --------- | ----------------------------------------------- |
+| `AssetId`      | Reference | Created/updated asset ID (nillable)             |
+| `ErrorCode`    | String    | Error type reference code (nillable)            |
+| `ErrorMessage` | String    | Error information (nillable)                    |
+| `EventUuid`    | String    | Platform event message UUID (nillable)          |
+| `IsSuccess`    | Boolean   | Request success status (default: false, v61.0+) |
+| `OrderItemId`  | Reference | Order item ID used in request (v61.0+)          |
+| `ReplayId`     | String    | Event stream position (nillable)                |
 
 **Supported Subscribers:** Apex Triggers, Flows, Processes, Pub/Sub API,
 Streaming API (CometD)

package/package.json

@@ -1,32 +1,33 @@
 {
-  "name": "agent-docs",
-  "version": "1.0.1",
-  "type": "module",
-  "description": "A tool for generating reusable, low-token AI agent instruction documents",
-  "keywords": [
-    "ai",
-    "agent",
-    "documentation",
-    "docs",
-    "ide",
-    "cursor"
-  ],
-  "author": "starch-uk",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/starch-uk/agent-docs.git"
-  },
-  "devDependencies": {
-    "prettier": "^3.7.4"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "scripts": {
-    "format": "prettier --write \"**/*.{ts,md,json,yml,yaml}\"",
-    "format:fix": "prettier --write \"**/*.{ts,md,json,yml,yaml}\"",
-    "format:check": "prettier --check \"**/*.{ts,md,json,yml,yaml}\"",
-    "postinstall": "node postinstall.mjs"
-  }
-}
+	"name": "agent-docs",
+	"version": "1.1.0",
+	"type": "module",
+	"description": "A tool for generating reusable, low-token AI agent instruction documents",
+	"scripts": {
+		"format": "prettier --write \"**/*.{ts,md,json,yml,yaml}\"",
+		"format:fix": "prettier --write \"**/*.{ts,md,json,yml,yaml}\"",
+		"format:check": "prettier --check \"**/*.{ts,md,json,yml,yaml}\"",
+		"postinstall": "node postinstall.mjs"
+	},
+	"packageManager": "pnpm@10.27.0",
+	"keywords": [
+		"ai",
+		"agent",
+		"documentation",
+		"docs",
+		"ide",
+		"cursor"
+	],
+	"author": "starch-uk",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/starch-uk/agent-docs.git"
+	},
+	"devDependencies": {
+		"prettier": "^3.7.4"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	}
+}