Codeneos · Codeneos · May 14, 2026 · May 15, 2026
diff --git a/README.md b/README.md
@@ -1,52 +1,65 @@
-# **Vlocode**: Vlocity/Salesforce support libraries
+<img src="https://raw.githubusercontent.com/Codeneos/vlocode/main/packages/vscode-extension/resources/logo1.png" height="140">
 
-This is the monorepo root for all _@vlocode_ packages and the Vlocode VSCode extension. For information on the **Vlocode** VSCode extension [click here](packages/vscode-extension/README.md).
+# Vlocode &mdash; Salesforce Industries / OmniStudio (Vlocity) tooling
+
+This is the monorepo for the [**Vlocode** VS Code extension](packages/vscode-extension/README.md) and a set of reusable `@vlocode/*` libraries that power it. Together they provide a fast, modern toolchain for Salesforce Industries, OmniStudio and standard Salesforce metadata development &mdash; without depending on the Vlocity Build Tools.
+
+For the VS Code extension and end-user documentation see [`packages/vscode-extension`](packages/vscode-extension/README.md).
 
 ## Packages
 
--   [**@vlocode/util**](packages/util) - re-unable utility functions and classes
--   [**@vlocode/vlocity-deploy**](packages/vlocity-deploy) - high performance Vlocity DataPack deployment library
--   [**@vlocode/core**](packages/core) - IoC core and logging framework
--   [**@vlocode/salesforce**](packages/salesforce) - Salesforce specific classes and functions
--   [**Vlocode**](packages/vscode-extension) - Vlocode VSCode extension
--   [**@vlocode/cli**](packages/cli) - Vlocode Standalone DataPack deployment CLI
+| Package | Description |
+| --- | --- |
+| [**Vlocode**](packages/vscode-extension) | The VS Code extension for Salesforce Industries / OmniStudio and Salesforce metadata development. |
+| [**@vlocode/cli**](packages/cli) | Stand-alone command-line Datapack deployment tool, ideal for CI/CD pipelines. |
+| [**@vlocode/vlocity-deploy**](packages/vlocity-deploy) | High-performance Vlocity Datapack deployment library &mdash; the engine behind the extension and the CLI. |
+| [**@vlocode/omniscript**](packages/omniscript) | Pure-JS OmniScript &rarr; LWC compiler and definition generator. |
+| [**@vlocode/salesforce**](packages/salesforce) | Salesforce connectivity (REST, SOAP, Bulk, Metadata, Tooling) and high-level services. |
+| [**@vlocode/apex**](packages/apex) | ANTLR4-based APEX & SOQL parser. |
+| [**@vlocode/vlocity**](packages/vlocity) | Shared Vlocity domain types and matching-key logic. |
+| [**@vlocode/sass**](packages/sass) | Out-of-process SASS/SCSS transpiler used to compile Vlocity UI Templates. |
+| [**@vlocode/core**](packages/core) | IoC container, logging framework and filesystem abstraction. |
+| [**@vlocode/util**](packages/util) | General-purpose utilities (iterables, caching, async, XML, decorators, ...). |
+| [**@vlocode/vscode-webviews**](packages/vscode-webviews) | Angular webviews hosted by the VS Code extension. |
 
 ## Setup development environment
 
-Vlocode uses `pnpm` as package manager and lerna release manager. To setup a developer environment for Vlocode you should always use the latest LTS version of node with corepack. VScode is the preferred IDE for developing and debugging.
+Vlocode uses `pnpm` as package manager and `lerna-lite` for releases. Use the latest LTS version of Node with corepack. VS Code is the preferred IDE.
 
--   check out this repository
--   enable corepack and activate the `pnpm` package manager
+-   Check out this repository
+-   Enable corepack and activate the pinned `pnpm` version
 
-```shell
-$ corepack enable
-$ corepack prepare $(node -p "require('./package.json').packageManager") --activate
-```
+    ```shell
+    corepack enable
+    corepack prepare $(node -p "require('./package.json').packageManager") --activate
+    ```
 
--   install all dependencies using pnpm, this will install all dependencies for packages in the monorepo
+-   Install all dependencies (this links the workspace packages):
 
-```shell
-pnpm install
-```
+    ```shell
+    pnpm install
+    ```
 
--   open the folder in VSCode and start coding; the `launch.json` and `tasks.json` that are part of this repository should allow you to run both the Vlocode CLI as well as debug the Vlocode extension without requiring any configuration
+-   Open the folder in VS Code. The committed `launch.json` and `tasks.json` let you run the CLI and debug the extension without further configuration.
 
 ## Tests
 
-Each vlocode package comes with unit tests. To run all tests simply run `pnpm test` from the root folder which will run all package tests. P
+Each package ships with Jest unit tests. From the repo root:
 
-Vlocode uses jest as test runner and is pre-configured to generate a test converge report.
+```shell
+pnpm test
+```
 
-**Note** you should run `pnpm build` if you are not running a watcher to ensure that all packages are transpiled and linked under _node_modules_.
+Run `pnpm build` first if you are not running a watcher, so all packages are transpiled and linked under `node_modules`.
 
-## Beta (Prerelease) Versions
+## Beta (prerelease) versions
 
-You can cut and publish a beta (preview) version of all packages and the VSCode extension using the new `release-beta` script. Beta builds:
+You can cut and publish a beta of all packages and the extension with the `release-beta` script. Beta builds:
 
-- use semantic version prerelease identifiers (e.g. `1.34.0-beta.0`)
-- are published to GitHub Releases marked as *Pre-release*
-- are uploaded to the VSCode Marketplace as *Preview* (using `vsce --pre-release`)
-- can be iterated (`beta.1`, `beta.2`, ...); when you later publish a stable version (e.g. `1.34.0`) the preview flag is removed automatically by Marketplace
+-   use semantic-version prerelease identifiers (e.g. `1.34.0-beta.0`)
+-   are published to GitHub Releases marked as *Pre-release*
+-   are uploaded to the VS Code Marketplace as *Preview* (`vsce --pre-release`)
+-   can be iterated (`beta.1`, `beta.2`, ...) and are removed automatically when you later publish a stable version
 
 ### Creating a beta
 
@@ -56,9 +69,9 @@ pnpm release-beta
 
 This runs `lerna version prerelease --preid beta` which:
 
-1. Determines the next prerelease version for each changed package (conventional commits)
-2. Updates `lerna.json` + individual `package.json` versions (e.g. `1.34.0-beta.0`)
-3. Commits the changes and creates a git tag `v1.34.0-beta.0`
+1.  Determines the next prerelease version for each changed package (conventional commits)
+2.  Updates `lerna.json` and each `package.json` (e.g. `1.34.0-beta.0`)
+3.  Commits the changes and creates a git tag `v1.34.0-beta.0`
 
 Push the tag to trigger the GitHub Actions `Release` workflow:
 
@@ -68,30 +81,30 @@ git push origin HEAD --follow-tags
 
 ### Publishing flow (CI)
 
-The GitHub Actions release workflow detects prerelease versions (hyphen in the version) and automatically:
+The release workflow detects prerelease versions (hyphen in the version) and automatically:
 
-- passes `--pre-release` to the extension packaging & publish steps
-- marks the GitHub Release as pre-release when the version contains a hyphen
-- publishes all `@vlocode/*` npm packages with the `beta` dist-tag (so they don't overwrite `latest`)
+-   passes `--pre-release` to the extension packaging & publish steps
+-   marks the GitHub Release as pre-release
+-   publishes all `@vlocode/*` npm packages with the `beta` dist-tag (so they do not overwrite `latest`)
 
 ### Consuming beta npm packages
 
-Install a beta version by either specifying the full version or using the `beta` tag:
+Install a beta version by tag or explicit version:
 
 ```shell
 pnpm add @vlocode/core@beta
-pnpm add @vlocode/util@1.34.0-beta.0   # explicit version example
+pnpm add @vlocode/util@1.34.0-beta.0
 ```
 
-To upgrade back to the stable channel later:
+To go back to the stable channel later:
 
 ```shell
 pnpm up @vlocode/core@latest @vlocode/util@latest
 ```
 
-### Manually publishing the extension beta (optional)
+### Manually publishing the extension beta
 
-If you need to publish locally (e.g. testing credentials):
+Only needed when testing credentials locally:
 
 ```shell
 pnpm publish-extension-beta
@@ -104,8 +117,12 @@ This builds the extension and runs `vsce publish --pre-release` in the extension
 When ready for GA:
 
 ```shell
-pnpm release-minor   # or release-patch / manual lerna version command
+pnpm release-minor   # or release-patch / a manual lerna version command
 git push origin HEAD --follow-tags
 ```
 
-GitHub Actions will package without the prerelease flag and publish a normal release.
+GitHub Actions then packages without the prerelease flag and publishes a normal release.
+
+## License
+
+[MIT](LICENSE)
diff --git a/packages/apex/README.md b/packages/apex/README.md
@@ -1,38 +1,24 @@
 [![CI](https://github.com/Codeneos/vlocode/actions/workflows/ci.yml/badge.svg)](https://github.com/Codeneos/vlocode/actions/workflows/ci.yml)
-[![GitHub top language](https://img.shields.io/github/languages/top/codeneos/vlocode.svg?logo=github)](https://github.com/Codeneos/vlocode)
-[![Bugs](https://img.shields.io/sonar/https/sonarcloud.io/curlybracket.vlocode/bugs.svg?color=lightgray&label=bugs&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAolBMVEUAAAD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgCXdjhZAAAANXRSTlMA%2Bg335ykFAwnr7hDZON7Ie1ZDMfTUmIUUSSLPoVAa4r6K8rtyXD62gG2xpsKSjnZpYx6qTp5XIo8AAAOWSURBVFjD7VbZtqIwEGSVRXYQAVFBFvf16v%2F%2F2tgJKsYEvPM4Z%2FLiwV7SXV2phPu3lyB71fnserLwN9HD%2BGBL4u2%2BRMk%2BeMJvw887CH6uIKuGvwhXvIK%2FEYtf1sq38epRu1GWtFa%2FLH%2FPNxFFvq6q9aGQ8LeYC19hH2L30VFWm4p8Z4Tb2H%2BRYbBC%2B2urWfvfy1hHGZx%2BHNwFeBox4alMDfhfv%2FbFJxNUvvlpqVEGe9aTYAxe85pmihGWTne8bEGnJ7qx5KG5pDNBCZssBcZ8M7CeOkcILuKUCTAP6bvo5GuAE5P1ESAsyR0JKqhxzLYfACG3ZwY8dMDsoWcOKXDFZ9tNYFnYQeMNkPh09fzZgD5loMKWfYxrREOeF3VjU%2FqUHMn8bp8w5Elwl4tba2nbTwWRNSRPBUWeFHMjkgqirckMXuPDFx5hUtcSGU4b%2BemV3BHeSHpoUut2uirL8XYSwNfCJEDetjQyjFrtNyJmjE3cnBJ54b3dgmhVBgytfIRTpENChPQ8aYNSHxzy4DkoTrmMseju1XcRmg64L866eL0nj1ER4rkZ7oghQuScgadNWz5ijIVBzlkiRCDoQKOB25Dagqhw8ECGP%2FXGHwOEwKPvCj4184HMpk%2Fwo72IGpWfzEEjze8WGwqL%2BwrIMbNafrUO52LGefCb9RUwtFG82ybvBnaecsd%2BrQYEfgD0d6lZ4x6gFdGj3%2FLDV2H%2B0tr4FHVZcjaUllDnvppk8etrRqrxzAJUOQNIGLEEcHTpwAVpNIfSRCyFDcwOZu6ACbgC6o25Quj0VrAjhINAuWInuGAMUtiHyqMp333L1AFQmCuZbr7WSTHMoBVngpsd0UCCCetm50W88DihgB5c5mNjz0oQB3hnjNWOVoKpA8Amo4Dl4wwkBupFoR4AgGnIfq7M5ScYOq0JD9jO5wPmgwmDH%2B2Qpk0%2FKyjxa32lfsYjRZtcmo0kfJERE4vyoHnihgRT1TOK0J97ngLk92MOWk5XKKxZtiu0CvNTXNlReQmu2FzIbgLlKoJ8XuLtdQ0XUZxkAfzVyzSV8N02Vtvd6s2NN8%2FSMNzaEo%2B%2F525sPG5a%2BycM08xqLAtHfX8Kj26UlZmgRTzFYlTkbJK9RjrNHUSvYWmQFj2UKbQxQ6u1Fz8ay8ojuTMR24nTekAX0aQKd5am65KRHaZvo4vivDAkfaFZdnhOKOEt7ZR9XwYBJZeKLJf7LP4vYv0BK5jBy9A2z3IAAAAASUVORK5CYII%3D)](https://sonarcloud.io/dashboard?id=curlybracket.vlocode)
-[![Vulnerabilities](https://img.shields.io/sonar/https/sonarcloud.io/curlybracket.vlocode/vulnerabilities.svg?label=vulnerabilities&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAolBMVEUAAAD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgCXdjhZAAAANXRSTlMA%2Bg335ykFAwnr7hDZON7Ie1ZDMfTUmIUUSSLPoVAa4r6K8rtyXD62gG2xpsKSjnZpYx6qTp5XIo8AAAOWSURBVFjD7VbZtqIwEGSVRXYQAVFBFvf16v%2F%2F2tgJKsYEvPM4Z%2FLiwV7SXV2phPu3lyB71fnserLwN9HD%2BGBL4u2%2BRMk%2BeMJvw887CH6uIKuGvwhXvIK%2FEYtf1sq38epRu1GWtFa%2FLH%2FPNxFFvq6q9aGQ8LeYC19hH2L30VFWm4p8Z4Tb2H%2BRYbBC%2B2urWfvfy1hHGZx%2BHNwFeBox4alMDfhfv%2FbFJxNUvvlpqVEGe9aTYAxe85pmihGWTne8bEGnJ7qx5KG5pDNBCZssBcZ8M7CeOkcILuKUCTAP6bvo5GuAE5P1ESAsyR0JKqhxzLYfACG3ZwY8dMDsoWcOKXDFZ9tNYFnYQeMNkPh09fzZgD5loMKWfYxrREOeF3VjU%2FqUHMn8bp8w5Elwl4tba2nbTwWRNSRPBUWeFHMjkgqirckMXuPDFx5hUtcSGU4b%2BemV3BHeSHpoUut2uirL8XYSwNfCJEDetjQyjFrtNyJmjE3cnBJ54b3dgmhVBgytfIRTpENChPQ8aYNSHxzy4DkoTrmMseju1XcRmg64L866eL0nj1ER4rkZ7oghQuScgadNWz5ijIVBzlkiRCDoQKOB25Dagqhw8ECGP%2FXGHwOEwKPvCj4184HMpk%2Fwo72IGpWfzEEjze8WGwqL%2BwrIMbNafrUO52LGefCb9RUwtFG82ybvBnaecsd%2BrQYEfgD0d6lZ4x6gFdGj3%2FLDV2H%2B0tr4FHVZcjaUllDnvppk8etrRqrxzAJUOQNIGLEEcHTpwAVpNIfSRCyFDcwOZu6ACbgC6o25Quj0VrAjhINAuWInuGAMUtiHyqMp333L1AFQmCuZbr7WSTHMoBVngpsd0UCCCetm50W88DihgB5c5mNjz0oQB3hnjNWOVoKpA8Amo4Dl4wwkBupFoR4AgGnIfq7M5ScYOq0JD9jO5wPmgwmDH%2B2Qpk0%2FKyjxa32lfsYjRZtcmo0kfJERE4vyoHnihgRT1TOK0J97ngLk92MOWk5XKKxZtiu0CvNTXNlReQmu2FzIbgLlKoJ8XuLtdQ0XUZxkAfzVyzSV8N02Vtvd6s2NN8%2FSMNzaEo%2B%2F525sPG5a%2BycM08xqLAtHfX8Kj26UlZmgRTzFYlTkbJK9RjrNHUSvYWmQFj2UKbQxQ6u1Fz8ay8ojuTMR24nTekAX0aQKd5am65KRHaZvo4vivDAkfaFZdnhOKOEt7ZR9XwYBJZeKLJf7LP4vYv0BK5jBy9A2z3IAAAAASUVORK5CYII%3D)](https://sonarcloud.io/dashboard?id=curlybracket.vlocode)
-![NPM Version](https://img.shields.io/npm/v/%40vlocode%5Capex)
+![NPM Version](https://img.shields.io/npm/v/%40vlocode%2Fapex)
 
-# **@vlocode/apex** Salesforce APEX Language Parser
+# @vlocode/apex &mdash; APEX & SOQL parser
 
-Antlr4 based [APEX Parser](./src/grammar/ApexParser.ts) and [Grammar](./grammar/ApexParser.g4). This library uses [antlr4ng](https://github.com/mike-lischke/antlr4ng) as runtime library which is a port of the original antlr4 runtime library to TypeScript.
-
-The library exposes the APEX Lexer and APEX parser generated from the `.g4` grammar files allowing parsing of APEX source code using Visitor or Listener patterns.
+An ANTLR4-based [APEX parser](./src/grammar/ApexParser.ts) and [grammar](./grammar/ApexParser.g4) for Node.js and the browser. Built on [`antlr4ng`](https://github.com/mike-lischke/antlr4ng) (the TypeScript port of the original ANTLR4 runtime), it exposes the APEX lexer and parser plus a small set of higher-level helpers built on top of them.
 
 ## Features
 
--   Full APEX and SOQL grammar support
--   Extract code structure from APEX source code
--   Identify classes, fields, methods, properties and access modifiers
--   Identify which classes are tested by which test classes
-
-## Example: Identifying test classes for a given class
-
-Below code demonstrates how to identify which classes are tested by which test classes. And prints the test classes for a given class name.
+-   Full APEX *and* SOQL grammar support
+-   Walk the parse tree with the standard ANTLR Visitor / Listener patterns
+-   Extract code structure (classes, fields, methods, properties, access modifiers) from raw source
+-   Identify which classes are exercised by which test classes &mdash; useful for delta-test selection in CI
 
-```ts
-import { TestIdentifier } from '@vlocode/apex';
+## Install
 
-const testIdentifier = container.create(TestIdentifier);
-await testIdentifier.loadApexClasses(['path/to/apex/classes']);
-const testClasses = testIdentifier.getTestClasses('MyClass');
-console.log(testClasses);
+```shell
+npm install @vlocode/apex
 ```
 
-## Example: Extracting class information from APEX source code
-
-Below code demonstrates how to extract class information from an APEX source fragment and prints the class name, fields and methods as well as their access modifiers.
+## Example: extract class structure from APEX source
 
 ```ts
 import { Parser } from '@vlocode/apex';
@@ -45,12 +31,12 @@ const sourceCode = `public class Person {
         get { return this.name; }
     }
 
-    public Integer getAge(Integer arg) {
+    public Integer getAge() {
         return this.age;
     }
 
     public Date getBirthDate() {
-        return Date.now();
+        return Date.today();
     }
 }`;
 
@@ -72,18 +58,31 @@ for (const classInfo of struct.classes) {
 }
 ```
 
-Outputs the following:
+Output:
 
-```shell
+```text
 Class Person
  Fields: 2
   1) name (private)
   2) age (private)
  Methods: 2
-  2) getAge (public)
-  3) getBirthDate (public)
+  1) getAge (public)
+  2) getBirthDate (public)
+```
+
+## Example: find tests for a class
+
+```ts
+import { TestIdentifier } from '@vlocode/apex';
+import { container } from '@vlocode/core';
+
+const testIdentifier = container.create(TestIdentifier);
+await testIdentifier.loadApexClasses(['path/to/apex/classes']);
+
+const testClasses = testIdentifier.getTestClasses('MyClass');
+console.log(testClasses); // ['MyClassTest', 'IntegrationTest', ...]
 ```
 
 ## Credits
 
-The grammar files in this library are based on the grammar files from the `apex-parser` NPM library originally maintained by Andrey Gavrikov. The original library is no longer maintained and the grammar files have been updated to work with the latest version of Salesforce and the antlr4ng runtime library.
+The grammar files are adapted from the original `apex-parser` library by Andrey Gavrikov. That project is no longer maintained, so we updated the grammar to track newer APEX language features and the `antlr4ng` runtime.