@@ -0,0 +1,50 @@
+# Project Guidelines
+
+## Architecture
+- `marklogic-client-api`: core Java client library for interacting with the MarkLogic REST API.
+- `ml-development-tools`: Gradle plugin and generators for Data Services endpoint proxies/tests.
+- `marklogic-client-api-functionaltests`: functional/regression-style tests, split into fragile/fast/slow groups.
+- `test-app`: ml-gradle deployment project that provisions test infrastructure in MarkLogic.
+- `examples`: supporting code used by tests and usage examples.
+
+## Build And Test
+- Prefer Gradle from the repo root.
+- Quick compile verification: `./gradlew clean build -x test`
+- Core module tests: `./gradlew marklogic-client-api:test`
+- Plugin tests (includes generated tests workflow): `./gradlew ml-development-tools:test`
+- Functional tests must run in this order to reduce flakiness:
+  1. `./gradlew marklogic-client-api-functionaltests:runFragileTests`
+  2. `./gradlew marklogic-client-api-functionaltests:runFastFunctionalTests`
+  3. `./gradlew marklogic-client-api-functionaltests:runSlowFunctionalTests`
+
+## Test Environment
+- Java 17+ is required for current releases.
+- Most tests require a running MarkLogic instance and deployed test resources.
+- Typical setup sequence:
+  1. `docker compose up -d --build`
+  2. `./gradlew -i mlWaitTillReady`
+  3. `./gradlew -i mlDeploy`
+  4. Run module tests
+- Override local MarkLogic connection settings via `gradle-local.properties` (`mlHost`, `mlPassword`).
+
+## Quality Controls
+- Treat compile warnings as failures: project builds enforce `-Xlint:unchecked`, `-Xlint:deprecation`, and `-Werror`.
+- Keep dependency security constraints intact (e.g. forced/excluded dependencies for CVE mitigation in Gradle files).
+- When adding or changing first-party Java/Kotlin code, run security scanning steps used by this workspace workflow before finalizing changes.
+- Do not relax quality gates (tests/compilation) to make a change pass; fix the underlying issue.
+
+## Code Generation And Automation
+- Data Services proxy generation is automated; use `generateEndpointProxies` instead of hand-writing proxy classes.
+- `ml-development-tools` test automation uses `generateTests` and `fixMjsModulesForMarkLogic12` before `test`.
+- Generated sources commonly include an "IMPORTANT: Do not edit" header. Regenerate from source declarations instead of editing generated output directly.
+- For changes affecting generation logic, validate both generator behavior and generated artifact compilation/tests.
+
+## Conventions For Changes
+- Keep edits scoped to the target module; avoid cross-module churn unless required.
+- Prefer existing patterns in nearby code over introducing new abstractions.
+- For test-related fixes, document whether behavior changes impact unit tests, functional tests, or deployment setup.
+
+## Docs To Link (Do Not Duplicate)
+- `README.md`: product overview, dependency usage, Java compatibility.
+- `CONTRIBUTING.md`: local build/test workflow and MarkLogic test setup.
+- `ml-development-tools/src/test/example-project/README.md`: plugin-focused usage/testing notes.
@@ -36,6 +36,7 @@ xml-with-props.xml
 ml-development-tools/src/test/ml-modules
 ml-development-tools/src/test/java/com/marklogic/client/test/dbfunction/generated
 
+.codesight
 .vscode
 docker/
 
 
@@ -2,4 +2,4 @@
 # Each line is a file pattern followed by one or more owners.
 
 # These owners will be the default owners for everything in the repo.
-* @billfarber @rjrudin @stevebio
+* @rjrudin @jonmille @ngodugu-marklogic @RitaChen609 @rjdew-progress
@@ -1,5 +1,5 @@
-To develop the Java Client and ultimately submit a pull request, you'll first need to be able to build the client and 
-run the tests locally. 
+To develop the Java Client and ultimately submit a pull request, you'll first need to be able to build the client and
+run the tests locally.
 
 Please see [this guide](.github/CONTRIBUTING.md) for information on creating and submitting a pull request.
 
@@ -11,7 +11,7 @@ To build the client locally, complete the following steps:
 4. Verify that you can build the client by running `./gradlew build -x test`
 
 "Running the tests" in the context of developing and submitting a pull request refers to running the tests found
-in the `marklogic-client-api` module. The tests for this module depend on a 
+in the `marklogic-client-api` module. The tests for this module depend on a
 [ml-gradle](https://github.com/marklogic-community/ml-gradle) application being deployed from the `test-app` module.
 This application contains a number of database and security resources that the tests depend on.
 The `./gradle.properties` file defines the connection properties for this application; these default
@@ -53,5 +53,5 @@ You can also undeploy the test application if you do not wish to keep it around
 
     ./gradlew mlUndeploy -i -Pconfirm=true
 
-To test the `ml-development-tools` Gradle plugin, see the README.md file located at 
+To test the `ml-development-tools` Gradle plugin, see the README.md file located at
 `ml-development-tools/src/test/example-project`.
@@ -135,8 +135,6 @@ pipeline {
 	environment {
 		JAVA_HOME_DIR = getJavaHomePath()
 		GRADLE_DIR = ".gradle"
-		DMC_USER = credentials('MLBUILD_USER')
-		DMC_PASSWORD = credentials('MLBUILD_PASSWORD')
 		PLATFORM = "linux/amd64"
 		MARKLOGIC_INSTALL_CONVERTERS = "true"
 	}
@@ -189,14 +187,35 @@ pipeline {
 				}
 			}
 			steps {
-				sh label: 'publish', script: '''#!/bin/bash
-					export JAVA_HOME=$JAVA_HOME_DIR
-					export GRADLE_USER_HOME=$WORKSPACE/$GRADLE_DIR
-					export PATH=$GRADLE_USER_HOME:$JAVA_HOME/bin:$PATH
-					cp ~/.gradle/gradle.properties $GRADLE_USER_HOME;
-					cd java-client-api
-					./gradlew publish
-        '''
+				withCredentials([
+					string(credentialsId: 'MLBUILD_USER', variable: 'DMC_USER'),
+					string(credentialsId: 'MLBUILD_PASSWORD', variable: 'DMC_PASSWORD')
+				]) {
+					sh label: 'publish', script: '''#!/bin/bash
+						export JAVA_HOME=$JAVA_HOME_DIR
+						export GRADLE_USER_HOME=$WORKSPACE/$GRADLE_DIR
+						export PATH=$GRADLE_USER_HOME:$JAVA_HOME/bin:$PATH
+						cp ~/.gradle/gradle.properties $GRADLE_USER_HOME;
+						cd java-client-api
+						./gradlew publish
+				'''
+				}
+			}
+			post {
+				always {
+					sh label: 'generate-javadoc', script: '''#!/bin/bash
+						export JAVA_HOME=$JAVA_HOME_DIR
+						export GRADLE_USER_HOME=$WORKSPACE/$GRADLE_DIR
+						export PATH=$GRADLE_USER_HOME:$JAVA_HOME/bin:$PATH
+						cd java-client-api
+						./gradlew javadoc
+						echo "Zipping javadocs for easy download..."
+						cd marklogic-client-api/build/docs
+						zip -r javadoc.zip javadoc/
+						mv javadoc.zip $WORKSPACE/
+	        '''
+					archiveArtifacts artifacts: 'javadoc.zip', fingerprint: true
+				}
 			}
 		}
 
@@ -210,7 +229,14 @@ pipeline {
 
 			steps {
 				script {
-					def imageTags = params.MARKLOGIC_IMAGE_TAGS.split(',')
+					// Validate MARKLOGIC_IMAGE_TAGS to prevent argument injection via user-supplied image tag values;
+					// each entry is validated individually after trimming to reject empty values and tags
+					// containing spaces or other shell-injectable characters
+					def imageTags = params.MARKLOGIC_IMAGE_TAGS.split(',').collect { it.trim() }
+					def invalidTags = imageTags.findAll { it.isEmpty() || !(it ==~ /^[a-z0-9]+(?:[._-][a-z0-9]+)*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?$/) }
+					if (!invalidTags.isEmpty()) {
+						error("Invalid MARKLOGIC_IMAGE_TAGS entries: ${invalidTags}. Expected comma-delimited docker image refs like 'marklogic-server-ubi:latest-12'")
+					}
 					def imagePrefix = 'ml-docker-db-dev-tierpoint.bed-artifactory.bedford.progress.com/marklogic/'
 
 					imageTags.each { tag ->
@@ -313,7 +339,7 @@ pipeline {
 			}
 		}
 
-		stage('regressions-11 arm infrastructure') {
+		stage('regressions-arm infrastructure') {
 			when {
 				beforeAgent true
 				branch 'develop'
@@ -334,14 +360,22 @@ pipeline {
 									submoduleCfg                     : [],
 									userRemoteConfigs                : scm.userRemoteConfigs])
 
-				runTests("ml-docker-db-dev-tierpoint.bed-artifactory.bedford.progress.com/marklogic/marklogic-server-ubi9-arm:latest-11")
-			}
-			post {
-				always {
-					archiveArtifacts artifacts: 'java-client-api/**/build/reports/**/*.html'
-					junit '**/build/**/TEST*.xml'
-					updateWorkspacePermissions()
-					tearDownDocker()
+				script {
+					def imagePrefix = 'ml-docker-db-dev-tierpoint.bed-artifactory.bedford.progress.com/marklogic/marklogic-server-ubi9-arm:'
+
+					['latest-11', 'latest-12'].each { tag ->
+						def fullImage = imagePrefix + tag
+						stage("regressions-arm-${tag}") {
+							try {
+								runTests(fullImage)
+							} finally {
+								archiveArtifacts artifacts: 'java-client-api/**/build/reports/**/*.html'
+								junit '**/build/**/TEST*.xml'
+								updateWorkspacePermissions()
+								tearDownDocker()
+							}
+						}
+					}
 				}
 			}
 		}