agent-docs 1.0.0 → 1.0.1

package/PLAN.md

@@ -49,8 +49,8 @@ The README.md should contain:
     - Instructions for adding the package to a project (as a dependency or
       submodule)
     - Explanation of the automatic `postinstall` behavior:
-        - When `@starch-uk/agent-docs` is installed into another project, a
-          `postinstall` script will run in the consuming project.
+        - 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/`
@@ -369,9 +369,9 @@ 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 create a symlink/junction from the consuming project's
-`docs/` directory to this package's `docs/` directory, but only if the consuming
-project doesn't already have a `docs/` directory.
+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.
 
 ```js
 // postinstall.mjs
@@ -608,7 +608,7 @@ Standard MIT license with copyright holder: starch-uk
 
 ### package.json
 
-- Name: `@starch-uk/agent-docs`
+- Name: `agent-docs`
 - Type: module
 - Version: `1.0.0`
 - Scripts: `format`, `format:fix`, `format:check`, `postinstall`
@@ -650,8 +650,8 @@ The plan should:
   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, VSCODE.md, XPATH31.md) need to be initialized with
-  version `1.0.0` (or appropriate version based on their current state) when the
+  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:

package/README.md

@@ -40,26 +40,24 @@ with any technology.
 2. **Add to your project:**
 
     You can add agent-docs to your project in several ways:
-    - **As an npm dependency (recommended):**  
-      Add `@starch-uk/agent-docs` to your `package.json` and install with your
-      package manager (e.g. `pnpm install`, `npm install`, or `yarn add`).
+    - **As an npm dependency (recommended):** Add `agent-docs` to your
+      `package.json` and install with your package manager (e.g. `pnpm install`,
+      `npm install`, or `yarn add`).
 
         When installed this way, a `postinstall` script runs in the consuming
         project:
         - If your project does **not** already have a `docs/` directory, the
-          script will create a single link from your project's `docs/` directory
-          to this package's `docs/` directory:
-            - On Unix/macOS, a directory symlink is created
-            - On Windows, a junction is created
+          script will copy this package's `docs/` directory to your project's
+          root directory
         - If your project **already has** a `docs/` directory, the script does
           nothing, and your existing docs layout is left unchanged.
 
     - **As a git submodule:**  
       `git submodule add https://github.com/starch-uk/agent-docs.git`
 
-    - **As a manual symlink/junction (if you want explicit control):**
-        - **Unix/macOS:** `ln -s /path/to/agent-docs/docs ./docs`
-        - **Windows:** `mklink /J docs C:\path\to\agent-docs\docs`
+    - **As a manual copy (if you want explicit control):**
+        - Copy the `docs/` directory from the agent-docs package to your project
+          root
 
 3. **Configure your IDE agent:**
 
@@ -78,39 +76,42 @@ with any technology.
 The `docs/` directory contains generated documentation files. Each doc follows a
 structured format optimized for AI agent consumption:
 
-- **APEXANNOTATIONS.md** - Apex annotations reference
-- **APEXDOC.md** - ApexDoc documentation tool reference
-- **CML.md** - Constraint Modeling Language (CML) reference for Salesforce
-  Revenue Cloud Product Configurator
-- **CODEANALYZER.md** - Salesforce Code Analyzer configuration (includes CLI
-  Commands, CPD Engine, Flow Scanner Engine, Regex Engine, RetireJS Engine, and
-  MCP tools)
-- **CONTEXTDEFINITIONS.md** - Salesforce Context Definitions reference for
-  Dynamic Revenue Orchestrator (DRO)
-- **ESLINT.md** - ESLint configuration and rules reference
-- **ESLINTJSDOC.md** - ESLint JSDoc plugin reference
-- **FIELDSERVICE.md** - Salesforce Field Service reference
-- **GRAPHBINARY.md** - Graph Binary format reference
-- **GRAPHENGINE.md** - Graph Engine reference
-- **GRAPHML.md** - GraphML format reference
-- **GRAPHSON.md** - GraphSON format reference
-- **GREMLIN.md** - Gremlin query language reference
-- **GRYO.md** - Gryo binary format reference
-- **HUSKY.md** - Husky git hooks tool reference
-- **JEST.md** - Jest testing framework reference
-- **JORJE.md** - Jorje Apex parser reference
-- **JSDOC.md** - JSDoc documentation generator reference
-- **PMD.md** - PMD static analysis tool reference (includes Apex AST reference
-  and suppressing warnings)
-- **PNPM.md** - pnpm package manager reference
-- **PRETTIER.md** - Prettier code formatter reference
-- **PRETTIERAPEX.md** - Prettier Apex plugin reference
-- **REVENUETRANSACTIONMANAGEMENT.md** - Salesforce Revenue Cloud Transaction
-  Management reference
-- **TINKERPOP.md** - Apache TinkerPop graph computing framework reference
-- **VITEST.md** - Vitest testing framework reference
-- **VSCODE.md** - VS Code editor reference
-- **XPATH31.md** - XPath 3.1 query language 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
+  Salesforce Revenue Cloud Product Configurator
+- **[CODEANALYZER.md](docs/CODEANALYZER.md)** - Salesforce Code Analyzer
+  configuration (includes CLI Commands, CPD Engine, Flow Scanner Engine, Regex
+  Engine, RetireJS Engine, and MCP tools)
+- **[CONTEXTDEFINITIONS.md](docs/CONTEXTDEFINITIONS.md)** - Salesforce Context
+  Definitions reference for Dynamic Revenue Orchestrator (DRO)
+- **[ESLINT.md](docs/ESLINT.md)** - ESLint configuration and rules reference
+- **[ESLINTJSDOC.md](docs/ESLINTJSDOC.md)** - ESLint JSDoc plugin reference
+- **[FIELDSERVICE.md](docs/FIELDSERVICE.md)** - Salesforce Field Service
+  reference
+- **[GRAPHBINARY.md](docs/GRAPHBINARY.md)** - Graph Binary format reference
+- **[GRAPHENGINE.md](docs/GRAPHENGINE.md)** - Graph Engine reference
+- **[GRAPHML.md](docs/GRAPHML.md)** - GraphML format reference
+- **[GRAPHSON.md](docs/GRAPHSON.md)** - GraphSON format reference
+- **[GREMLIN.md](docs/GREMLIN.md)** - Gremlin query language reference
+- **[GRYO.md](docs/GRYO.md)** - Gryo binary format reference
+- **[HUSKY.md](docs/HUSKY.md)** - Husky git hooks tool reference
+- **[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
+- **[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
+- **[PRETTIER.md](docs/PRETTIER.md)** - Prettier code formatter reference
+- **[PRETTIERAPEX.md](docs/PRETTIERAPEX.md)** - Prettier Apex plugin reference
+- **[REVENUETRANSACTIONMANAGEMENT.md](docs/REVENUETRANSACTIONMANAGEMENT.md)** -
+  Salesforce Revenue Cloud Transaction Management reference
+- **[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
 
 ## Contributing
 

package/docs/CODEANALYZER.md

@@ -308,6 +308,91 @@ Requires network
 
 ---
 
+## VS Code Integration
+
+> **Version**: 1.0.0
+
+Salesforce Code Analyzer Visual Studio Code Extension provides real-time
+feedback and code scanning during development.
+
+**Reference**:
+[Use the VS Code Extension to Analyze Your Code](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/analyze-vscode.html)
+
+### Prerequisites
+
+- Visual Studio Code installed
+- Salesforce CLI installed and configured
+- Salesforce Extensions for VS Code installed
+
+### Installation
+
+**Step 1: Install Salesforce CLI**
+
+```bash
+sf --version
+```
+
+**Step 2: Install Salesforce Extensions for VS Code**
+
+Extension pack includes Code Analyzer: Search "Salesforce Extension Pack" in VS
+Code Extensions.
+
+**Step 3: Install Code Analyzer CLI Plugin**
+
+```bash
+sf plugins install @salesforce/sfdx-scanner
+```
+
+Verify: `sf scanner --help`
+
+### Scanning Commands
+
+| Command                       | Description              | Access                         |
+| ----------------------------- | ------------------------ | ------------------------------ |
+| **SFDX: Scan Current File**   | Analyze active file      | Command Palette (Ctrl+Shift+P) |
+| **SFDX: Scan Selected Files** | Analyze selection        | Right-click Explorer           |
+| **SFDX: Scan Workspace**      | Analyze entire workspace | Command Palette                |
+
+### Results Display
+
+**Problems Panel** (Ctrl+Shift+M): Severity icons, file navigation, rule details
+
+**Inline Annotations**: Red/Yellow/Blue squiggles by severity level
+
+**Quick Actions**: Go to definition, view rule details, copy violation
+
+### Configuration
+
+**Extension Settings** (VS Code Settings → "Salesforce Code Analyzer"):
+
+- Enable/Disable extension
+- Auto-scan on save
+- Default engine selection
+- Severity mapping to VS Code levels
+- Excluded file patterns
+
+**Project Config**: Respects `code-analyzer.yml` in project root
+
+### Troubleshooting
+
+| Issue                     | Solution                                                        |
+| ------------------------- | --------------------------------------------------------------- |
+| **Extension not working** | Verify CLI/plugin installed, check Output panel, reload VS Code |
+| **No results**            | Check file types supported, verify config, review Output panel  |
+| **Slow performance**      | Exclude patterns, disable auto-scan, scan selectively           |
+| **Plugin not found**      | Reinstall plugin, check CLI compatibility, restart VS Code      |
+
+### Best Practices
+
+1. Customize `code-analyzer.yml` for team standards
+2. Scan regularly during development
+3. Prioritize High/Critical severity fixes
+4. Use rule tags ("Recommended") for focus
+5. Understand rule rationale before fixing
+6. Exclude generated/third-party code
+
+---
+
 ## CI/CD Integration
 
 ### GitHub Actions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-docs",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "A tool for generating reusable, low-token AI agent instruction documents",
   "keywords": [

package/postinstall.mjs

@@ -17,6 +17,21 @@ const packageDocsDir = path.join(packageRoot, 'docs');
 // The docs directory in the consumer project
 const consumerDocsDir = path.join(consumerRoot, 'docs');
 
+async function copyDirRecursive(src, dest) {
+  const stats = await fs.promises.stat(src);
+  if (stats.isDirectory()) {
+    await fs.promises.mkdir(dest, { recursive: true });
+    const entries = await fs.promises.readdir(src);
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry);
+      const destPath = path.join(dest, entry);
+      await copyDirRecursive(srcPath, destPath);
+    }
+  } else {
+    await fs.promises.copyFile(src, dest);
+  }
+}
+
 async function main() {
   try {
     // Ensure this package actually has a docs directory
@@ -31,18 +46,14 @@ async function main() {
       return;
     }
 
-    const isWindows = process.platform === 'win32';
+    // Copy the docs directory instead of creating symlinks
+    // This is more reliable across different environments
+    await copyDirRecursive(packageDocsDir, consumerDocsDir);
 
-    if (isWindows) {
-      // On Windows, create a junction from consumerRoot/docs to this package's docs
-      // Junction target must be an absolute path
-      await fs.promises.symlink(packageDocsDir, consumerDocsDir, 'junction');
-    } else {
-      // On POSIX, create a directory symlink
-      await fs.promises.symlink(packageDocsDir, consumerDocsDir, 'dir');
-    }
-  } catch {
-    // Never fail install because of docs-linking issues
+  } catch (error) {
+    // Never fail install because of docs-copying issues
+    // In production, this should be silent, but for debugging we'll leave it
+    console.warn('Warning: Failed to copy agent-docs to consumer docs directory:', error.message);
   }
 }
 

package/docs/VSCODE.md

@@ -1,231 +0,0 @@
-# VS Code Extension for Code Analyzer
-
-> **Version**: 1.0.0
-
-## Overview
-
-The Salesforce Code Analyzer Visual Studio Code Extension integrates Code
-Analyzer's static analysis capabilities directly into the VS Code environment,
-providing real-time feedback and code scanning during development.
-
-**Reference:**
-[Use the VS Code Extension to Analyze Your Code](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/analyze-vscode.html)
-
-## Prerequisites
-
-- Visual Studio Code installed
-- Salesforce CLI installed and configured
-- Salesforce Extensions for VS Code installed
-
-## Installation
-
-### Step 1: Install Salesforce CLI
-
-Ensure Salesforce CLI is installed on your system:
-
-```bash
-sf --version
-```
-
-If not installed, download from
-[Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli).
-
-### Step 2: Install Salesforce Extensions for VS Code
-
-The Code Analyzer extension is included in the Salesforce Extensions for VS Code
-extension pack:
-
-1. Open VS Code
-2. Go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
-3. Search for "Salesforce Extension Pack"
-4. Click Install
-
-Alternatively, install the Code Analyzer extension directly by searching for
-"Salesforce Code Analyzer".
-
-### Step 3: Install Code Analyzer CLI Plugin
-
-The VS Code extension requires the Code Analyzer CLI plugin. Install it via
-terminal:
-
-```bash
-sf plugins install @salesforce/sfdx-scanner
-```
-
-Or open the VS Code integrated terminal (Ctrl+` / Cmd+`) and run:
-
-```bash
-sf plugins install @salesforce/sfdx-scanner
-```
-
-Verify installation:
-
-```bash
-sf scanner --help
-```
-
-## Usage
-
-### Scan Selected Files or Folders
-
-1. In VS Code Explorer, select one or more files or folders
-2. Right-click the selection
-3. Choose **"SFDX: Scan Selected Files or Folders with Code Analyzer"**
-
-The extension will analyze the selected items and display results in the
-Problems panel.
-
-### Scan Current File
-
-1. Open a file in the editor
-2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
-3. Type and select **"SFDX: Scan Current File with Code Analyzer"**
-
-The current file will be analyzed and violations will be shown in the Problems
-panel.
-
-### Scan Workspace
-
-To scan the entire workspace:
-
-1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
-2. Type and select **"SFDX: Scan Workspace with Code Analyzer"**
-
-## Viewing Results
-
-### Problems Panel
-
-After scanning, results are displayed in the **Problems** panel (View → Problems
-or Ctrl+Shift+M / Cmd+Shift+M):
-
-- **Severity**: Indicated by icon color (Error/Warning/Info)
-- **File**: Click to navigate to the violation location
-- **Rule**: Rule name and description
-- **Line**: Line number where violation occurs
-- **Message**: Detailed violation message
-
-### Inline Annotations
-
-Violations appear as inline annotations in the editor:
-
-- Red squiggles for errors (High/Critical severity)
-- Yellow squiggles for warnings (Moderate severity)
-- Blue squiggles for info (Low/Info severity)
-
-Hover over annotations to see detailed violation information.
-
-### Quick Actions
-
-Right-click on a violation in the Problems panel or editor to access:
-
-- **Go to Definition**: Navigate to rule definition
-- **View Rule Details**: See full rule documentation
-- **Copy Violation**: Copy violation details to clipboard
-
-## Configuration
-
-### Extension Settings
-
-Configure Code Analyzer extension behavior via VS Code settings:
-
-1. Open Settings (Ctrl+, / Cmd+,)
-2. Search for "Salesforce Code Analyzer"
-
-Available settings:
-
-- **Enable/Disable**: Toggle Code Analyzer on/off
-- **Auto-scan on Save**: Automatically scan files when saved
-- **Default Engine**: Set default engine for scanning
-- **Severity Mapping**: Map Code Analyzer severities to VS Code severities
-- **Excluded Patterns**: Patterns to exclude from scanning
-
-### Project Configuration
-
-The extension respects `code-analyzer.yml` configuration in your project root.
-For detailed configuration options, see
-[Code Analyzer Configuration](CODEANALYZER.md).
-
-Example `code-analyzer.yml`:
-
-```yaml
-engines:
-    pmd:
-        custom_rulesets:
-            - rulesets/design/InnerClassesCannotBeStatic.xml
-
-rules:
-    pmd:
-        NoSingleLetterVariableNames:
-            severity: 'High'
-            tags: ['Recommended']
-```
-
-## Keyboard Shortcuts
-
-Default keyboard shortcuts:
-
-- **Scan Current File**: Not assigned by default (use Command Palette)
-- **Scan Selected Files**: Not assigned by default (use context menu)
-
-You can assign custom shortcuts via:
-
-1. File → Preferences → Keyboard Shortcuts (Ctrl+K Ctrl+S / Cmd+K Cmd+S)
-2. Search for "Salesforce Code Analyzer"
-3. Assign desired shortcuts
-
-## Troubleshooting
-
-### Extension Not Working
-
-1. Verify Salesforce CLI is installed and in PATH
-2. Verify Code Analyzer plugin is installed: `sf plugins list`
-3. Check VS Code Output panel for errors (View → Output, select "Salesforce Code
-   Analyzer")
-4. Reload VS Code window (Ctrl+Shift+P → "Developer: Reload Window")
-
-### No Results Displayed
-
-1. Verify files are supported file types (`.cls`, `.trigger`, `.js`, `.ts`,
-   `.html`, `.cmp`, etc.)
-2. Check `code-analyzer.yml` configuration
-3. Verify rules are enabled and not filtered out
-4. Check VS Code Output panel for scanning errors
-
-### Slow Performance
-
-1. Exclude unnecessary files via `code-analyzer.yml` patterns
-2. Disable auto-scan on save for large workspaces
-3. Scan individual files/folders instead of entire workspace
-4. Check system resources (CPU, memory)
-
-### Plugin Not Found
-
-If extension reports CLI plugin not found:
-
-1. Verify plugin installation: `sf plugins list | grep scanner`
-2. Reinstall plugin: `sf plugins install @salesforce/sfdx-scanner --force`
-3. Check Salesforce CLI version compatibility
-4. Restart VS Code
-
-## Best Practices
-
-1. **Configure Rules**: Customize `code-analyzer.yml` to match your team's
-   standards
-2. **Regular Scanning**: Scan code regularly during development, not just before
-   commits
-3. **Fix High Priority**: Address High and Critical severity violations first
-4. **Use Tags**: Leverage rule tags (e.g., "Recommended") to focus on important
-   rules
-5. **Review Results**: Don't blindly fix all violations; understand rule
-   rationale
-6. **Exclude Patterns**: Exclude generated files and third-party code from
-   scanning
-
-## Related Documentation
-
-- **[CLI Commands](CODEANALYZER.md#cli-commands)** - Command-line usage of Code
-  Analyzer
-- **[Code Analyzer Configuration](CODEANALYZER.md)** - Complete configuration
-  reference
-- **[PMD Engine](PMD.md)** - PMD rules and configuration
-- **[ESLint Engine](ESLINT.md)** - ESLint rules for JavaScript/TypeScript/LWC