diff --git a/README.md b/README.md
index 1713675..5e88223 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,18 @@
 
 *   [`templates/`](./templates): A collection of minimal, use-case-specific projects. We recommend starting with one of these templates.
 
+## How AutoRepro Submissions Work
+
+Each AutoRepro project's main purpose is to generate an `autorepro-submission.zip` file for your report.
+
+You declare metadata about your test using the DSL blocks (e.g., `appTest {}`, `submission {}`) provided by the `com.android.security.autorepro.*` plugins in your `build.gradle.kts` files.
+
+There are two key Gradle tasks:
+1.  `./gradlew assembleSubmissionSources`: This task compiles the metadata from your DSL blocks into a `manifest.json` file, which it places in an intermediate `build/autorepro-submission/` directory along with your source code.
+2.  `./gradlew assembleSubmissionZip`: This task packages the contents of that intermediate directory into the final `autorepro-submission.zip`.
+
+Our internal systems parse the `autorepro-submission.zip` file, using the `manifest.json` inside it to reconstruct your test. Because the it's based on the generated manifest and not the Gradle files, any custom Gradle logic in your build files is not part of the final submission and will be ignored.
+
 ## What is the "AutoRepro Placeholder"?
 
 Throughout the projects, you will find variants of the string `autorepro_placeholder` used in package names, resource files, and other identifiers.
diff --git a/example/settings.gradle.kts b/example/settings.gradle.kts
index 13a00ec..de470dd 100644
--- a/example/settings.gradle.kts
+++ b/example/settings.gradle.kts
@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
 // repositories of plugins
 pluginManagement {
     repositories {
diff --git a/example/submission/appTest/build.gradle.kts b/example/submission/appTest/build.gradle.kts
index ee315d0..aeb648f 100644
--- a/example/submission/appTest/build.gradle.kts
+++ b/example/submission/appTest/build.gradle.kts
@@ -13,7 +13,16 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-plugins { id("com.android.security.autorepro.apptest") }
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/AppTestPlugin.kt
+    id("com.android.security.autorepro.apptest")
+}
 
 // Note: the Gradle package name is appended to the namespace "com.android.security"
+
+// This DSL configures the submission manifest.json.
 appTest {}
diff --git a/example/submission/appTest2/build.gradle.kts b/example/submission/appTest2/build.gradle.kts
index cf91cdf..aeb648f 100644
--- a/example/submission/appTest2/build.gradle.kts
+++ b/example/submission/appTest2/build.gradle.kts
@@ -13,6 +13,16 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-plugins { id("com.android.security.autorepro.apptest") }
 
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/AppTestPlugin.kt
+    id("com.android.security.autorepro.apptest")
+}
+
+// Note: the Gradle package name is appended to the namespace "com.android.security"
+
+// This DSL configures the submission manifest.json.
 appTest {}
diff --git a/example/submission/build.gradle.kts b/example/submission/build.gradle.kts
index 9f62006..7edbb43 100644
--- a/example/submission/build.gradle.kts
+++ b/example/submission/build.gradle.kts
@@ -1,4 +1,26 @@
-plugins { id("com.android.security.autorepro.submission") }
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/SubmissionPlugin.kt
+    id("com.android.security.autorepro.submission")
+}
 
 fun getSubprojects(): List<Project> {
     // glob for gradle direct subprojects
@@ -21,6 +43,5 @@
     getSubprojects().forEach { testResource(it) }
 }
 
-submission {
-    // Please configure your submission attributes here
-}
+// This DSL configures the submission manifest.json.
+submission {}
diff --git a/example/submission/hostTest/build.gradle.kts b/example/submission/hostTest/build.gradle.kts
index 7222155..b05a995 100644
--- a/example/submission/hostTest/build.gradle.kts
+++ b/example/submission/hostTest/build.gradle.kts
@@ -13,4 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-plugins { id("com.android.security.autorepro.javahosttest") }
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/JavaHostTestPlugin.kt
+    id("com.android.security.autorepro.javahosttest")
+}
diff --git a/example/submission/ndkTest/build.gradle.kts b/example/submission/ndkTest/build.gradle.kts
index 60ddb7a..8bec37c 100644
--- a/example/submission/ndkTest/build.gradle.kts
+++ b/example/submission/ndkTest/build.gradle.kts
@@ -1,7 +1,28 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
 plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/NdkTestPlugin.kt
     id("com.android.security.autorepro.ndktest")
 }
 
+// This DSL configures the submission manifest.json.
 nativeTest {
     minSdk = 33
     targetSdk = 33
diff --git a/templates/same-app-id/settings.gradle.kts b/templates/same-app-id/settings.gradle.kts
index 13a00ec..de470dd 100644
--- a/templates/same-app-id/settings.gradle.kts
+++ b/templates/same-app-id/settings.gradle.kts
@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
 // repositories of plugins
 pluginManagement {
     repositories {
diff --git a/templates/same-app-id/submission/appTestV1/build.gradle.kts b/templates/same-app-id/submission/appTestV1/build.gradle.kts
index 0b5e2ec..b6e604c 100644
--- a/templates/same-app-id/submission/appTestV1/build.gradle.kts
+++ b/templates/same-app-id/submission/appTestV1/build.gradle.kts
@@ -13,7 +13,16 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-plugins { id("com.android.security.autorepro.apptest") }
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/AppTestPlugin.kt
+    id("com.android.security.autorepro.apptest")
+}
 
 // Note: the Gradle package name is appended to the namespace "com.android.security"
+
+// This DSL configures the submission manifest.json.
 appTest {}
diff --git a/templates/same-app-id/submission/appTestV2/build.gradle.kts b/templates/same-app-id/submission/appTestV2/build.gradle.kts
index 8977cd0..69aeb70 100644
--- a/templates/same-app-id/submission/appTestV2/build.gradle.kts
+++ b/templates/same-app-id/submission/appTestV2/build.gradle.kts
@@ -13,9 +13,19 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-plugins { id("com.android.security.autorepro.apptest") }
 
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/AppTestPlugin.kt
+    id("com.android.security.autorepro.apptest")
+}
+
+// Note: the Gradle package name is appended to the namespace "com.android.security"
+
+// This DSL configures the submission manifest.json.
 appTest {
-  // Set the applicationId to match the v1 package name
-  applicationId = "com.android.security.appTestV1"
+    // Set the applicationId to match the v1 package name
+    applicationId = "com.android.security.appTestV1"
 }
diff --git a/templates/same-app-id/submission/build.gradle.kts b/templates/same-app-id/submission/build.gradle.kts
index 9f62006..7edbb43 100644
--- a/templates/same-app-id/submission/build.gradle.kts
+++ b/templates/same-app-id/submission/build.gradle.kts
@@ -1,4 +1,26 @@
-plugins { id("com.android.security.autorepro.submission") }
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/SubmissionPlugin.kt
+    id("com.android.security.autorepro.submission")
+}
 
 fun getSubprojects(): List<Project> {
     // glob for gradle direct subprojects
@@ -21,6 +43,5 @@
     getSubprojects().forEach { testResource(it) }
 }
 
-submission {
-    // Please configure your submission attributes here
-}
+// This DSL configures the submission manifest.json.
+submission {}
diff --git a/templates/same-app-id/submission/hostTest/build.gradle.kts b/templates/same-app-id/submission/hostTest/build.gradle.kts
index a26d538..c542806 100644
--- a/templates/same-app-id/submission/hostTest/build.gradle.kts
+++ b/templates/same-app-id/submission/hostTest/build.gradle.kts
@@ -13,4 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-plugins { id("com.android.security.autorepro.javahosttest") }
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/JavaHostTestPlugin.kt
+    id("com.android.security.autorepro.javahosttest")
+}
diff --git a/templates/single-app/settings.gradle.kts b/templates/single-app/settings.gradle.kts
index 13a00ec..de470dd 100644
--- a/templates/single-app/settings.gradle.kts
+++ b/templates/single-app/settings.gradle.kts
@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
 // repositories of plugins
 pluginManagement {
     repositories {
diff --git a/templates/single-app/submission/appTest/build.gradle.kts b/templates/single-app/submission/appTest/build.gradle.kts
index ee315d0..aeb648f 100644
--- a/templates/single-app/submission/appTest/build.gradle.kts
+++ b/templates/single-app/submission/appTest/build.gradle.kts
@@ -13,7 +13,16 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-plugins { id("com.android.security.autorepro.apptest") }
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/AppTestPlugin.kt
+    id("com.android.security.autorepro.apptest")
+}
 
 // Note: the Gradle package name is appended to the namespace "com.android.security"
+
+// This DSL configures the submission manifest.json.
 appTest {}
diff --git a/templates/single-app/submission/build.gradle.kts b/templates/single-app/submission/build.gradle.kts
index 9f62006..7edbb43 100644
--- a/templates/single-app/submission/build.gradle.kts
+++ b/templates/single-app/submission/build.gradle.kts
@@ -1,4 +1,26 @@
-plugins { id("com.android.security.autorepro.submission") }
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/SubmissionPlugin.kt
+    id("com.android.security.autorepro.submission")
+}
 
 fun getSubprojects(): List<Project> {
     // glob for gradle direct subprojects
@@ -21,6 +43,5 @@
     getSubprojects().forEach { testResource(it) }
 }
 
-submission {
-    // Please configure your submission attributes here
-}
+// This DSL configures the submission manifest.json.
+submission {}
diff --git a/templates/single-app/submission/hostTest/build.gradle.kts b/templates/single-app/submission/hostTest/build.gradle.kts
index 7222155..b05a995 100644
--- a/templates/single-app/submission/hostTest/build.gradle.kts
+++ b/templates/single-app/submission/hostTest/build.gradle.kts
@@ -13,4 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-plugins { id("com.android.security.autorepro.javahosttest") }
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/JavaHostTestPlugin.kt
+    id("com.android.security.autorepro.javahosttest")
+}
diff --git a/templates/single-ndk/settings.gradle.kts b/templates/single-ndk/settings.gradle.kts
index 13a00ec..de470dd 100644
--- a/templates/single-ndk/settings.gradle.kts
+++ b/templates/single-ndk/settings.gradle.kts
@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
 // repositories of plugins
 pluginManagement {
     repositories {
diff --git a/templates/single-ndk/submission/build.gradle.kts b/templates/single-ndk/submission/build.gradle.kts
index 9f62006..7edbb43 100644
--- a/templates/single-ndk/submission/build.gradle.kts
+++ b/templates/single-ndk/submission/build.gradle.kts
@@ -1,4 +1,26 @@
-plugins { id("com.android.security.autorepro.submission") }
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/SubmissionPlugin.kt
+    id("com.android.security.autorepro.submission")
+}
 
 fun getSubprojects(): List<Project> {
     // glob for gradle direct subprojects
@@ -21,6 +43,5 @@
     getSubprojects().forEach { testResource(it) }
 }
 
-submission {
-    // Please configure your submission attributes here
-}
+// This DSL configures the submission manifest.json.
+submission {}
diff --git a/templates/single-ndk/submission/hostTest/build.gradle.kts b/templates/single-ndk/submission/hostTest/build.gradle.kts
index 7222155..b05a995 100644
--- a/templates/single-ndk/submission/hostTest/build.gradle.kts
+++ b/templates/single-ndk/submission/hostTest/build.gradle.kts
@@ -13,4 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-plugins { id("com.android.security.autorepro.javahosttest") }
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
+plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/JavaHostTestPlugin.kt
+    id("com.android.security.autorepro.javahosttest")
+}
diff --git a/templates/single-ndk/submission/ndkTest/build.gradle.kts b/templates/single-ndk/submission/ndkTest/build.gradle.kts
index 60ddb7a..8bec37c 100644
--- a/templates/single-ndk/submission/ndkTest/build.gradle.kts
+++ b/templates/single-ndk/submission/ndkTest/build.gradle.kts
@@ -1,7 +1,28 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// IMPORTANT: Do not add any custom Gradle logic to this file.
+
 plugins {
+    // Note: The plugin on Google Maven may be newer than the public source.
+    // Plugin source code: https://android.googlesource.com/platform/platform_testing/+/main/libraries/sts-common-util/autorepro/plugin/autorepro/src/main/kotlin/com/android/security/autorepro/NdkTestPlugin.kt
     id("com.android.security.autorepro.ndktest")
 }
 
+// This DSL configures the submission manifest.json.
 nativeTest {
     minSdk = 33
     targetSdk = 33