From fff0ff1c13ca3b8f451da72c11002be6ec029aee Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 10:57:46 +0200
Subject: [PATCH 01/11] Make @SimpleBuilder @Inherited to match documentation
 (#244)

The class-level Javadoc and docs/CONFIGURATION.md implied that
@SimpleBuilder is inherited by subclasses, but the annotation was not
meta-annotated with @Inherited. As a result BuilderProcessor, which
collects types via RoundEnvironment.getElementsAnnotatedWith(...),
only produced builders for the exact type carrying @SimpleBuilder and
not for unannotated subclasses.

Add @Inherited to @SimpleBuilder so subclasses are treated as if they
also carried the annotation, mirroring the existing behaviour of
@SimpleBuilder.Template (which is already @Inherited). Update the
Javadoc to document the inheritance explicitly and clarify the
CONFIGURATION.md wording. @Ignore4BuilderGeneration still suppresses
generation for the exact type it is placed on, so opt-outs continue
to work as before.

Add SimpleBuilderInheritanceTest covering direct inheritance, the
opt-out interaction, and multi-level (grandchild) inheritance.

Closes #244

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../core/annotations/SimpleBuilder.java       |   7 +
 docs/CONFIGURATION.md                         |   2 +-
 .../SimpleBuilderInheritanceTest.java         | 222 ++++++++++++++++++
 3 files changed, 230 insertions(+), 1 deletion(-)
 create mode 100644 processor/src/test/java/org/javahelpers/simple/builders/processor/SimpleBuilderInheritanceTest.java

diff --git a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
index 46bbf140..271409ba 100644
--- a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
+++ b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
@@ -54,6 +54,12 @@
  *
  * <p>Use {@link Template} to create reusable configuration presets.
  *
+ * <p>This annotation is {@link Inherited}: a subclass of an annotated type is treated as if it also
+ * carried {@code @SimpleBuilder}, unless it is explicitly excluded via {@link
+ * Ignore4BuilderGeneration}. The {@link Template} meta-annotation is {@link Inherited} as well, so
+ * custom template annotations that are themselves {@code @Inherited} propagate to subclasses in the
+ * same way.
+ *
  * <p>Related annotations:
  *
  * <ul>
@@ -70,6 +76,7 @@
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.CLASS)
+@Inherited
 public @interface SimpleBuilder {
 
   /**
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index ee10d325..2b775a6c 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -120,7 +120,7 @@ public class PersonDto {
 
 ## Excluding Types from Builder Generation
 
-You can opt a whole DTO out of builder generation with `@Ignore4BuilderGeneration`. This is useful when a class inherits `@SimpleBuilder` or an `@SimpleBuilder.Template` annotation from a parent and you do not want a builder for that specific subclass.
+You can opt a whole DTO out of builder generation with `@Ignore4BuilderGeneration`. This is useful when a class inherits `@SimpleBuilder` (which is itself `@Inherited`) or an `@SimpleBuilder.Template`-based annotation from a parent and you do not want a builder for that specific subclass.
 
 ```java
 import org.javahelpers.simple.builders.core.annotations.Ignore4BuilderGeneration;
diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/SimpleBuilderInheritanceTest.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/SimpleBuilderInheritanceTest.java
new file mode 100644
index 00000000..28471af6
--- /dev/null
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/SimpleBuilderInheritanceTest.java
@@ -0,0 +1,222 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2026 Andreas Igel
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.javahelpers.simple.builders.processor;
+
+import static com.google.testing.compile.CompilationSubject.assertThat;
+import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.assertContaining;
+import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.assertGenerationSucceeded;
+import static org.javahelpers.simple.builders.processor.testing.ProcessorTestUtils.loadGeneratedSource;
+
+import com.google.testing.compile.Compilation;
+import javax.tools.JavaFileObject;
+import org.javahelpers.simple.builders.processor.testing.ProcessorTestUtils;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tests for inheritance of {@code @SimpleBuilder}, which is meta-annotated with {@code @Inherited}
+ * so that unannotated subclasses of an annotated parent also get a builder. See <a
+ * href="https://github.com/java-helpers/simple-builders/issues/244">issue #244</a>.
+ */
+class SimpleBuilderInheritanceTest {
+
+  private Compilation compile(JavaFileObject... sourceFiles) {
+    return ProcessorTestUtils.createCompiler().compile(sourceFiles);
+  }
+
+  /**
+   * Asserts that no generated source file for the given class builder exists.
+   *
+   * @param compilation the compilation result
+   * @param className the simple class name for which no builder should have been generated
+   * @param message the failure message
+   */
+  private void assertNoBuilderGenerated(Compilation compilation, String className, String message) {
+    Assertions.assertTrue(
+        compilation.generatedSourceFiles().stream()
+            .noneMatch(f -> f.getName().endsWith(className + "Builder.java")),
+        message);
+  }
+
+  /**
+   * An unannotated subclass of a class annotated with {@code @SimpleBuilder} must itself get a
+   * builder, because {@code @SimpleBuilder} is {@code @Inherited}. The parent's builder is still
+   * generated as well.
+   */
+  @Test
+  void unannotatedSubclassGetsBuilderFromInheritedSimpleBuilder() {
+    JavaFileObject parentSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            import org.javahelpers.simple.builders.core.annotations.SimpleBuilder;
+
+            @SimpleBuilder
+            public class ParentDto {
+                private String name;
+
+                public String getName() { return name; }
+                public void setName(String name) { this.name = name; }
+            }
+            """);
+
+    JavaFileObject childSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            public class ChildDto extends ParentDto {
+                private int age;
+
+                public int getAge() { return age; }
+                public void setAge(int age) { this.age = age; }
+            }
+            """);
+
+    Compilation compilation = compile(parentSource, childSource);
+
+    assertThat(compilation).succeededWithoutWarnings();
+
+    String parentBuilder = loadGeneratedSource(compilation, "ParentDtoBuilder");
+    assertGenerationSucceeded(compilation, "ParentDtoBuilder", parentBuilder);
+    assertContaining(parentBuilder, "public ParentDtoBuilder name(String name)");
+
+    String childBuilder = loadGeneratedSource(compilation, "ChildDtoBuilder");
+    assertGenerationSucceeded(compilation, "ChildDtoBuilder", childBuilder);
+    // The child builder must expose setters for both the inherited field and its own field.
+    assertContaining(childBuilder, "public ChildDtoBuilder name(String name)");
+    assertContaining(childBuilder, "public ChildDtoBuilder age(int age)");
+  }
+
+  /**
+   * A subclass annotated with {@code @Ignore4BuilderGeneration} must NOT get a builder even though
+   * it would otherwise inherit {@code @SimpleBuilder} from its parent. The parent's builder is
+   * still generated.
+   */
+  @Test
+  void subclassOptedOutViaIgnoreDoesNotGetInheritedBuilder() {
+    JavaFileObject parentSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            import org.javahelpers.simple.builders.core.annotations.SimpleBuilder;
+
+            @SimpleBuilder
+            public class ParentDto {
+                private String name;
+
+                public String getName() { return name; }
+                public void setName(String name) { this.name = name; }
+            }
+            """);
+
+    JavaFileObject childSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            import org.javahelpers.simple.builders.core.annotations.Ignore4BuilderGeneration;
+
+            @Ignore4BuilderGeneration
+            public class ChildDto extends ParentDto { }
+            """);
+
+    Compilation compilation = compile(parentSource, childSource);
+
+    assertThat(compilation).succeededWithoutWarnings();
+
+    String parentBuilder = loadGeneratedSource(compilation, "ParentDtoBuilder");
+    assertGenerationSucceeded(compilation, "ParentDtoBuilder", parentBuilder);
+
+    assertNoBuilderGenerated(
+        compilation,
+        "ChildDto",
+        "ChildDto builder should not have been generated due to @Ignore4BuilderGeneration");
+  }
+
+  /**
+   * A grandchild of an annotated type must also inherit {@code @SimpleBuilder} across multiple
+   * levels of the type hierarchy.
+   */
+  @Test
+  void grandchildInheritsSimpleBuilderAcrossMultipleLevels() {
+    JavaFileObject parentSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            import org.javahelpers.simple.builders.core.annotations.SimpleBuilder;
+
+            @SimpleBuilder
+            public class GrandParentDto {
+                private String name;
+
+                public String getName() { return name; }
+                public void setName(String name) { this.name = name; }
+            }
+            """);
+
+    JavaFileObject middleSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            public class MiddleDto extends GrandParentDto {
+                private int age;
+
+                public int getAge() { return age; }
+                public void setAge(int age) { this.age = age; }
+            }
+            """);
+
+    JavaFileObject childSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            public class ChildDto extends MiddleDto {
+                private boolean active;
+
+                public boolean isActive() { return active; }
+                public void setActive(boolean active) { this.active = active; }
+            }
+            """);
+
+    Compilation compilation = compile(parentSource, middleSource, childSource);
+
+    assertThat(compilation).succeededWithoutWarnings();
+
+    assertGenerationSucceeded(
+        compilation,
+        "GrandParentDtoBuilder",
+        loadGeneratedSource(compilation, "GrandParentDtoBuilder"));
+    assertGenerationSucceeded(
+        compilation, "MiddleDtoBuilder", loadGeneratedSource(compilation, "MiddleDtoBuilder"));
+    assertGenerationSucceeded(
+        compilation, "ChildDtoBuilder", loadGeneratedSource(compilation, "ChildDtoBuilder"));
+  }
+}

From 13a8fc8d753de0799058fb770587da7e4d75a47e Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 11:01:56 +0200
Subject: [PATCH 02/11] Rename to BuilderAnnotationInheritanceTest and cover
 Template inheritance

Rename SimpleBuilderInheritanceTest to BuilderAnnotationInheritanceTest
so the name reflects that it covers both builder-triggering annotations.
Add unannotatedSubclassGetsBuilderFromInheritedTemplate, which verifies
that a custom @Inherited template annotation (meta-annotated with
@SimpleBuilder.Template) propagates to unannotated subclasses, matching
the existing behaviour of @SimpleBuilder itself.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 ... => BuilderAnnotationInheritanceTest.java} | 78 ++++++++++++++++++-
 1 file changed, 75 insertions(+), 3 deletions(-)
 rename processor/src/test/java/org/javahelpers/simple/builders/processor/{SimpleBuilderInheritanceTest.java => BuilderAnnotationInheritanceTest.java} (72%)

diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/SimpleBuilderInheritanceTest.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java
similarity index 72%
rename from processor/src/test/java/org/javahelpers/simple/builders/processor/SimpleBuilderInheritanceTest.java
rename to processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java
index 28471af6..a4e6179c 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/SimpleBuilderInheritanceTest.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java
@@ -36,11 +36,15 @@
 import org.junit.jupiter.api.Test;
 
 /**
- * Tests for inheritance of {@code @SimpleBuilder}, which is meta-annotated with {@code @Inherited}
- * so that unannotated subclasses of an annotated parent also get a builder. See <a
+ * Tests for inheritance of builder-triggering annotations.
+ *
+ * <p>Both {@code @SimpleBuilder} and the {@code @SimpleBuilder.Template} meta-annotation are
+ * meta-annotated with {@code @Inherited}, so unannotated subclasses of an annotated parent also get
+ * a builder. Custom template annotations that are themselves {@code @Inherited} propagate to
+ * subclasses in the same way. See <a
  * href="https://github.com/java-helpers/simple-builders/issues/244">issue #244</a>.
  */
-class SimpleBuilderInheritanceTest {
+class BuilderAnnotationInheritanceTest {
 
   private Compilation compile(JavaFileObject... sourceFiles) {
     return ProcessorTestUtils.createCompiler().compile(sourceFiles);
@@ -111,6 +115,74 @@ public class ChildDto extends ParentDto {
     assertContaining(childBuilder, "public ChildDtoBuilder age(int age)");
   }
 
+  /**
+   * An unannotated subclass of a class carrying a custom {@code @Inherited} template annotation
+   * (meta-annotated with {@code @SimpleBuilder.Template}) must itself get a builder. The parent's
+   * builder is still generated as well, and the template's options apply to both.
+   */
+  @Test
+  void unannotatedSubclassGetsBuilderFromInheritedTemplate() {
+    JavaFileObject templateAnnotation =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            import java.lang.annotation.ElementType;
+            import java.lang.annotation.Inherited;
+            import java.lang.annotation.Retention;
+            import java.lang.annotation.RetentionPolicy;
+            import java.lang.annotation.Target;
+            import org.javahelpers.simple.builders.core.annotations.SimpleBuilder;
+
+            @SimpleBuilder.Template(options = @SimpleBuilder.Options())
+            @Inherited
+            @Retention(RetentionPolicy.CLASS)
+            @Target(ElementType.TYPE)
+            public @interface InheritedTemplate {}
+            """);
+
+    JavaFileObject parentSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            @InheritedTemplate
+            public class ParentDto {
+                private String name;
+
+                public String getName() { return name; }
+                public void setName(String name) { this.name = name; }
+            }
+            """);
+
+    JavaFileObject childSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            public class ChildDto extends ParentDto {
+                private int age;
+
+                public int getAge() { return age; }
+                public void setAge(int age) { this.age = age; }
+            }
+            """);
+
+    Compilation compilation = compile(templateAnnotation, parentSource, childSource);
+
+    assertThat(compilation).succeededWithoutWarnings();
+
+    String parentBuilder = loadGeneratedSource(compilation, "ParentDtoBuilder");
+    assertGenerationSucceeded(compilation, "ParentDtoBuilder", parentBuilder);
+    assertContaining(parentBuilder, "public ParentDtoBuilder name(String name)");
+
+    String childBuilder = loadGeneratedSource(compilation, "ChildDtoBuilder");
+    assertGenerationSucceeded(compilation, "ChildDtoBuilder", childBuilder);
+    // The child builder must expose setters for both the inherited field and its own field.
+    assertContaining(childBuilder, "public ChildDtoBuilder name(String name)");
+    assertContaining(childBuilder, "public ChildDtoBuilder age(int age)");
+  }
+
   /**
    * A subclass annotated with {@code @Ignore4BuilderGeneration} must NOT get a builder even though
    * it would otherwise inherit {@code @SimpleBuilder} from its parent. The parent's builder is

From 105310a272122ccb87f76f689f1398c8e5733bd1 Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 11:03:45 +0200
Subject: [PATCH 03/11] Refactoring code to move assertNoBuilderGenerated to
 common asserts

---
 .../BuilderAnnotationInheritanceTest.java      | 16 +---------------
 .../Ignore4BuilderGenerationTest.java          | 16 +---------------
 .../processor/testing/ProcessorAsserts.java    | 18 ++++++++++++++++++
 3 files changed, 20 insertions(+), 30 deletions(-)

diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java
index a4e6179c..663924ca 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java
@@ -27,12 +27,12 @@
 import static com.google.testing.compile.CompilationSubject.assertThat;
 import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.assertContaining;
 import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.assertGenerationSucceeded;
+import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.assertNoBuilderGenerated;
 import static org.javahelpers.simple.builders.processor.testing.ProcessorTestUtils.loadGeneratedSource;
 
 import com.google.testing.compile.Compilation;
 import javax.tools.JavaFileObject;
 import org.javahelpers.simple.builders.processor.testing.ProcessorTestUtils;
-import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 
 /**
@@ -50,20 +50,6 @@ private Compilation compile(JavaFileObject... sourceFiles) {
     return ProcessorTestUtils.createCompiler().compile(sourceFiles);
   }
 
-  /**
-   * Asserts that no generated source file for the given class builder exists.
-   *
-   * @param compilation the compilation result
-   * @param className the simple class name for which no builder should have been generated
-   * @param message the failure message
-   */
-  private void assertNoBuilderGenerated(Compilation compilation, String className, String message) {
-    Assertions.assertTrue(
-        compilation.generatedSourceFiles().stream()
-            .noneMatch(f -> f.getName().endsWith(className + "Builder.java")),
-        message);
-  }
-
   /**
    * An unannotated subclass of a class annotated with {@code @SimpleBuilder} must itself get a
    * builder, because {@code @SimpleBuilder} is {@code @Inherited}. The parent's builder is still
diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/Ignore4BuilderGenerationTest.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/Ignore4BuilderGenerationTest.java
index 31011bb5..3eb6c05b 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/Ignore4BuilderGenerationTest.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/Ignore4BuilderGenerationTest.java
@@ -27,6 +27,7 @@
 import static com.google.testing.compile.CompilationSubject.assertThat;
 import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.assertContaining;
 import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.assertGenerationSucceeded;
+import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.assertNoBuilderGenerated;
 import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.contains;
 import static org.javahelpers.simple.builders.processor.testing.ProcessorAsserts.notContains;
 import static org.javahelpers.simple.builders.processor.testing.ProcessorTestUtils.loadGeneratedSource;
@@ -35,7 +36,6 @@
 import javax.tools.JavaFileObject;
 import org.javahelpers.simple.builders.processor.testing.ProcessorAsserts;
 import org.javahelpers.simple.builders.processor.testing.ProcessorTestUtils;
-import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 
 /** Tests for the {@code @Ignore4BuilderGeneration} opt-out annotation. */
@@ -45,20 +45,6 @@ private Compilation compile(JavaFileObject... sourceFiles) {
     return ProcessorTestUtils.createCompiler().compile(sourceFiles);
   }
 
-  /**
-   * Asserts that no generated source file for the given class builder exists.
-   *
-   * @param compilation the compilation result
-   * @param className the simple class name for which no builder should have been generated
-   * @param message the failure message
-   */
-  private void assertNoBuilderGenerated(Compilation compilation, String className, String message) {
-    Assertions.assertTrue(
-        compilation.generatedSourceFiles().stream()
-            .noneMatch(f -> f.getName().endsWith(className + "Builder.java")),
-        message);
-  }
-
   /**
    * (a) A subclass that inherits a template annotation from its parent and is annotated with
    * {@code @Ignore4BuilderGeneration} must NOT get a builder, while the parent's builder is still
diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/testing/ProcessorAsserts.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/testing/ProcessorAsserts.java
index c5d94a2e..3c55dff3 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/testing/ProcessorAsserts.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/testing/ProcessorAsserts.java
@@ -119,6 +119,24 @@ public static void assertHadNoteContaining(Compilation compilation, String... no
     }
   }
 
+  /**
+   * Asserts that no generated source file for the given class' builder exists in the compilation.
+   *
+   * <p>The check is based on the simple class name: a file whose name ends with
+   * {@code <className>Builder.java} is considered the builder for {@code className}.
+   *
+   * @param compilation the compilation result
+   * @param className the simple class name for which no builder should have been generated
+   * @param message the failure message
+   */
+  public static void assertNoBuilderGenerated(
+      Compilation compilation, String className, String message) {
+    Assertions.assertTrue(
+        compilation.generatedSourceFiles().stream()
+            .noneMatch(f -> f.getName().endsWith(className + "Builder.java")),
+        message);
+  }
+
   /**
    * Asserts that the expected and actual strings are equal after normalizing whitespace.
    *

From 2c83b780d33e89ca07cea06b05111be5d9e826ec Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 11:04:05 +0200
Subject: [PATCH 04/11] fixing codeformat

---
 .../simple/builders/processor/testing/ProcessorAsserts.java   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/testing/ProcessorAsserts.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/testing/ProcessorAsserts.java
index 3c55dff3..ac6c4ecf 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/testing/ProcessorAsserts.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/testing/ProcessorAsserts.java
@@ -122,8 +122,8 @@ public static void assertHadNoteContaining(Compilation compilation, String... no
   /**
    * Asserts that no generated source file for the given class' builder exists in the compilation.
    *
-   * <p>The check is based on the simple class name: a file whose name ends with
-   * {@code <className>Builder.java} is considered the builder for {@code className}.
+   * <p>The check is based on the simple class name: a file whose name ends with {@code
+   * <className>Builder.java} is considered the builder for {@code className}.
    *
    * @param compilation the compilation result
    * @param className the simple class name for which no builder should have been generated

From aca9ef60c4f94ebe118e9313e662862f48d25cd6 Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 11:14:06 +0200
Subject: [PATCH 05/11] Document @Inherited behavior of @SimpleBuilder.Template

The Template Javadoc and CONFIGURATION.md "Template Annotations" section
did not explain that @SimpleBuilder.Template is @Inherited, nor that a
custom template annotation must additionally declare @Inherited to
propagate to unannotated subclasses. Add explicit documentation and an
example showing the @Inherited custom annotation pattern.

Also move assertNoBuilderGenerated to ProcessorAsserts so it is shared
by BuilderAnnotationInheritanceTest and Ignore4BuilderGenerationTest
instead of being duplicated as a private helper in each test class.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../core/annotations/SimpleBuilder.java       | 23 +++++++++++++++++++
 docs/CONFIGURATION.md                         | 17 ++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
index 271409ba..489beff7 100644
--- a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
+++ b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
@@ -704,6 +704,12 @@
    * custom annotation itself will be treated as @SimpleBuilder by the processor and will
    * automatically apply the configured options.
    *
+   * <p>This meta-annotation is {@link Inherited}. Note that this only controls inheritance of the
+   * {@code @SimpleBuilder.Template} meta-annotation itself; for a custom template annotation to
+   * propagate to unannotated subclasses, the custom annotation must additionally be declared with
+   * {@code @Inherited}. Without {@code @Inherited} on the custom annotation, only the exact type
+   * carrying it gets a builder.
+   *
    * <p>Example:
    *
    * <pre>{@code
@@ -723,6 +729,23 @@
    * }
    * }</pre>
    *
+   * <p>To make the template propagate to subclasses, add {@code @Inherited} to the custom
+   * annotation:
+   *
+   * <pre>{@code
+   * @SimpleBuilder.Template(options = @SimpleBuilder.Options(...))
+   * @Inherited
+   * @Retention(RetentionPolicy.CLASS)
+   * @Target(ElementType.TYPE)
+   * public @interface FullFeaturedBuilder {}
+   *
+   * @FullFeaturedBuilder
+   * public class ParentDto { ... }
+   *
+   * // ChildDto also gets a builder, because @FullFeaturedBuilder is @Inherited.
+   * public class ChildDto extends ParentDto { ... }
+   * }</pre>
+   *
    * <p>Related annotations:
    *
    * <ul>
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 2b775a6c..1f97ad81 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -118,6 +118,22 @@ public class PersonDto {
 }
 ```
 
+To make a template annotation propagate to unannotated subclasses, add `@Inherited` to it. `@SimpleBuilder` itself is `@Inherited`, and `@SimpleBuilder.Template` is `@Inherited` as well, but the custom annotation must also declare `@Inherited` for the processor to pick up subclasses:
+
+```java
+@SimpleBuilder.Template(options = @SimpleBuilder.Options(...))
+@Inherited
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.TYPE)
+public @interface MinimalBuilder {}
+
+@MinimalBuilder
+public class ParentDto { ... }
+
+// ChildDto also gets a builder, because @MinimalBuilder is @Inherited.
+public class ChildDto extends ParentDto { ... }
+```
+
 ## Excluding Types from Builder Generation
 
 You can opt a whole DTO out of builder generation with `@Ignore4BuilderGeneration`. This is useful when a class inherits `@SimpleBuilder` (which is itself `@Inherited`) or an `@SimpleBuilder.Template`-based annotation from a parent and you do not want a builder for that specific subclass.
@@ -1132,6 +1148,7 @@ Or in compiler options:
 2. **Verify options parameter**: Template must specify `options = @SimpleBuilder.Options(...)`
 3. **Retention and Target**: Add `@Retention(RetentionPolicy.CLASS)` and `@Target(ElementType.TYPE)`
 4. **Don't combine**: Don't use `@SimpleBuilder` when using a template annotation
+5. **Subclasses not getting a builder**: Add `@Inherited` to the custom template annotation so it propagates to unannotated subclasses (see [Template Annotations](#template-annotations) above). Without `@Inherited`, only the exact type carrying the annotation gets a builder.
 
 ### Builder Not Generated - Access Modifier Errors
 

From bd3bf9371b4621b0d979d61216ce4359d5caffd1 Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 11:20:32 +0200
Subject: [PATCH 06/11] Document options-inheritance limitation for inherited
 subclass builders
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

While @SimpleBuilder and @Inherited template annotations now correctly
trigger builder generation for unannotated subclasses, the configuration
options declared on the parent's @SimpleBuilder(options = ...) or template
are not yet applied to inherited subclass builders — they use default
options instead. This is tracked separately in issue #245.

Add caveats to the SimpleBuilder Javadoc, the CONFIGURATION.md Template
Annotations section, and the Template Annotations Not Working
troubleshooting section so users are not surprised by this limitation.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../builders/core/annotations/SimpleBuilder.java       | 10 ++++++----
 docs/CONFIGURATION.md                                  |  3 +++
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
index 489beff7..58cd7af9 100644
--- a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
+++ b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
@@ -55,10 +55,12 @@
  * <p>Use {@link Template} to create reusable configuration presets.
  *
  * <p>This annotation is {@link Inherited}: a subclass of an annotated type is treated as if it also
- * carried {@code @SimpleBuilder}, unless it is explicitly excluded via {@link
- * Ignore4BuilderGeneration}. The {@link Template} meta-annotation is {@link Inherited} as well, so
- * custom template annotations that are themselves {@code @Inherited} propagate to subclasses in the
- * same way.
+ * carried {@code @SimpleBuilder} for the purpose of triggering builder generation, unless it is
+ * explicitly excluded via {@link Ignore4BuilderGeneration}. The {@link Template} meta-annotation is
+ * {@link Inherited} as well, so custom template annotations that are themselves {@code @Inherited}
+ * propagate to subclasses in the same way. Note that configuration options declared on the parent's
+ * {@code @SimpleBuilder(options = ...)} or template are not yet applied to inherited subclass
+ * builders; subclasses currently use default options (see issue #245).
  *
  * <p>Related annotations:
  *
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 1f97ad81..1334d93b 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -134,6 +134,8 @@ public class ParentDto { ... }
 public class ChildDto extends ParentDto { ... }
 ```
 
+> **Note:** Inherited subclasses currently get a builder with **default options**, not the options declared on the parent's `@SimpleBuilder(options = ...)` or template. Options inheritance is tracked separately (see #245).
+
 ## Excluding Types from Builder Generation
 
 You can opt a whole DTO out of builder generation with `@Ignore4BuilderGeneration`. This is useful when a class inherits `@SimpleBuilder` (which is itself `@Inherited`) or an `@SimpleBuilder.Template`-based annotation from a parent and you do not want a builder for that specific subclass.
@@ -1149,6 +1151,7 @@ Or in compiler options:
 3. **Retention and Target**: Add `@Retention(RetentionPolicy.CLASS)` and `@Target(ElementType.TYPE)`
 4. **Don't combine**: Don't use `@SimpleBuilder` when using a template annotation
 5. **Subclasses not getting a builder**: Add `@Inherited` to the custom template annotation so it propagates to unannotated subclasses (see [Template Annotations](#template-annotations) above). Without `@Inherited`, only the exact type carrying the annotation gets a builder.
+6. **Subclass builder has wrong options**: Inherited subclass builders currently use default options, not the parent's `@SimpleBuilder.Options` or template options. This is a known limitation (see #245).
 
 ### Builder Not Generated - Access Modifier Errors
 

From e8e035245e4dc8e919c8b53a38296feb57b6f084 Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 12:13:00 +0200
Subject: [PATCH 07/11] Fix issue reference: #245 -> #248

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../simple/builders/core/annotations/SimpleBuilder.java       | 2 +-
 docs/CONFIGURATION.md                                         | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
index 58cd7af9..6d51b29d 100644
--- a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
+++ b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
@@ -60,7 +60,7 @@
  * {@link Inherited} as well, so custom template annotations that are themselves {@code @Inherited}
  * propagate to subclasses in the same way. Note that configuration options declared on the parent's
  * {@code @SimpleBuilder(options = ...)} or template are not yet applied to inherited subclass
- * builders; subclasses currently use default options (see issue #245).
+ * builders; subclasses currently use default options (see issue #248).
  *
  * <p>Related annotations:
  *
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 1334d93b..7449b4fe 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -134,7 +134,7 @@ public class ParentDto { ... }
 public class ChildDto extends ParentDto { ... }
 ```
 
-> **Note:** Inherited subclasses currently get a builder with **default options**, not the options declared on the parent's `@SimpleBuilder(options = ...)` or template. Options inheritance is tracked separately (see #245).
+> **Note:** Inherited subclasses currently get a builder with **default options**, not the options declared on the parent's `@SimpleBuilder(options = ...)` or template. Options inheritance is tracked separately (see #248).
 
 ## Excluding Types from Builder Generation
 
@@ -1151,7 +1151,7 @@ Or in compiler options:
 3. **Retention and Target**: Add `@Retention(RetentionPolicy.CLASS)` and `@Target(ElementType.TYPE)`
 4. **Don't combine**: Don't use `@SimpleBuilder` when using a template annotation
 5. **Subclasses not getting a builder**: Add `@Inherited` to the custom template annotation so it propagates to unannotated subclasses (see [Template Annotations](#template-annotations) above). Without `@Inherited`, only the exact type carrying the annotation gets a builder.
-6. **Subclass builder has wrong options**: Inherited subclass builders currently use default options, not the parent's `@SimpleBuilder.Options` or template options. This is a known limitation (see #245).
+6. **Subclass builder has wrong options**: Inherited subclass builders currently use default options, not the parent's `@SimpleBuilder.Options` or template options. This is a known limitation (see #248).
 
 ### Builder Not Generated - Access Modifier Errors
 

From 9776343a6e12f399bb56a2b31f17a81b7a1fb8b4 Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 18:04:42 +0200
Subject: [PATCH 08/11] Clarify @SimpleBuilder vs @SimpleBuilder.Template usage
 in docs

Add explicit guidance that @SimpleBuilder.Template is a meta-annotation
for custom annotation declarations (@interface) only and cannot be
placed directly on a class or record. @SimpleBuilder is for direct
one-off annotation of classes/records.

- SimpleBuilder.java: add 'When to use' section to class-level Javadoc
- SimpleBuilder.Template Javadoc: state it can only be placed on
  annotation types (ANNOTATION_TYPE), not on classes/records
- CONFIGURATION.md 'Template Annotations': add comparison table and
  introductory paragraph
- CONFIGURATION.md troubleshooting: add item about @SimpleBuilder.Template
  not being a class annotation

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../core/annotations/SimpleBuilder.java       | 27 +++++++++++++++----
 docs/CONFIGURATION.md                         | 12 +++++++--
 2 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
index 6d51b29d..fcbde632 100644
--- a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
+++ b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
@@ -33,10 +33,21 @@
 import org.javahelpers.simple.builders.core.enums.OptionState;
 
 /**
- * Annotation to mark classes for builder generation.
+ * Annotation to mark classes and records for builder generation.
  *
- * <p>Triggers generation of a fluent builder class with support for various patterns and helper
- * methods. Can be used standalone or combined with {@link Options} for fine-grained control.
+ * <p>Place this annotation directly on a class or record to trigger generation of a fluent builder
+ * class with support for various patterns and helper methods. Can be used standalone or combined
+ * with {@link Options} for fine-grained control.
+ *
+ * <p><b>When to use {@code @SimpleBuilder} vs {@link Template}:</b>
+ *
+ * <ul>
+ *   <li>Use {@code @SimpleBuilder} directly on a class/record for one-off builder generation.
+ *   <li>Use {@link Template} on a <b>custom annotation declaration</b> to create a reusable
+ *       configuration preset that can be applied to many classes. {@code @SimpleBuilder.Template}
+ *       cannot be placed on a class or record directly; it is only valid on annotation types
+ *       ({@link ElementType#ANNOTATION_TYPE}).
+ * </ul>
  *
  * <p>Available configuration options:
  *
@@ -702,10 +713,16 @@
   /**
    * Meta-annotation for creating custom SimpleBuilder annotation templates.
    *
-   * <p>This allows you to create custom annotations that pre-configure SimpleBuilder options. The
-   * custom annotation itself will be treated as @SimpleBuilder by the processor and will
+   * <p>This meta-annotation is placed on a <b>custom annotation declaration</b> (i.e., an
+   * {@code @interface}) to pre-configure SimpleBuilder options. The custom annotation can then be
+   * applied to classes and records just like {@link SimpleBuilder}, and the processor will
    * automatically apply the configured options.
    *
+   * <p>This annotation can <b>only</b> be placed on annotation types ({@link
+   * ElementType#ANNOTATION_TYPE}); it cannot be used directly on a class or record. Use {@link
+   * SimpleBuilder} for direct one-off annotation of classes, or use this meta-annotation to define
+   * a reusable custom annotation for a shared configuration across many classes.
+   *
    * <p>This meta-annotation is {@link Inherited}. Note that this only controls inheritance of the
    * {@code @SimpleBuilder.Template} meta-annotation itself; for a custom template annotation to
    * propagate to unannotated subclasses, the custom annotation must additionally be declared with
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 7449b4fe..ce56e05a 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -80,6 +80,13 @@ public class PersonDto {
 
 ## Template Annotations
 
+`@SimpleBuilder.Template` is a **meta-annotation**: it is placed on a custom annotation declaration (`@interface`), not directly on a class or record. Use it to create reusable configuration presets that can be applied to many classes with a single custom annotation. For one-off builder generation, use `@SimpleBuilder` directly on the class.
+
+| Need | Use |
+|------|-----|
+| Generate a builder for a single class/record | `@SimpleBuilder` on the class/record |
+| Share the same configuration across many classes | `@SimpleBuilder.Template` on a custom `@interface`, then the custom annotation on each class |
+
 Create reusable configuration presets with custom template annotations:
 
 ```java
@@ -1150,8 +1157,9 @@ Or in compiler options:
 2. **Verify options parameter**: Template must specify `options = @SimpleBuilder.Options(...)`
 3. **Retention and Target**: Add `@Retention(RetentionPolicy.CLASS)` and `@Target(ElementType.TYPE)`
 4. **Don't combine**: Don't use `@SimpleBuilder` when using a template annotation
-5. **Subclasses not getting a builder**: Add `@Inherited` to the custom template annotation so it propagates to unannotated subclasses (see [Template Annotations](#template-annotations) above). Without `@Inherited`, only the exact type carrying the annotation gets a builder.
-6. **Subclass builder has wrong options**: Inherited subclass builders currently use default options, not the parent's `@SimpleBuilder.Options` or template options. This is a known limitation (see #248).
+5. **Not a class annotation**: `@SimpleBuilder.Template` can only be placed on an annotation declaration (`@interface`), not directly on a class or record. Use `@SimpleBuilder` for direct class/record annotation, or create a custom annotation with `@SimpleBuilder.Template` and place that on the class.
+6. **Subclasses not getting a builder**: Add `@Inherited` to the custom template annotation so it propagates to unannotated subclasses (see [Template Annotations](#template-annotations) above). Without `@Inherited`, only the exact type carrying the annotation gets a builder.
+7. **Subclass builder has wrong options**: Inherited subclass builders currently use default options, not the parent's `@SimpleBuilder.Options` or template options. This is a known limitation (see #248).
 
 ### Builder Not Generated - Access Modifier Errors
 

From 4b7723a4fa022716be773f91eabf450b76bf256b Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 18:10:36 +0200
Subject: [PATCH 09/11] Link issue #248 from @SimpleBuilder.Template
 inheritance Javadoc

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../simple/builders/core/annotations/SimpleBuilder.java       | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
index fcbde632..abc4d56b 100644
--- a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
+++ b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
@@ -727,7 +727,9 @@
    * {@code @SimpleBuilder.Template} meta-annotation itself; for a custom template annotation to
    * propagate to unannotated subclasses, the custom annotation must additionally be declared with
    * {@code @Inherited}. Without {@code @Inherited} on the custom annotation, only the exact type
-   * carrying it gets a builder.
+   * carrying it gets a builder. As with {@link SimpleBuilder}, configuration options declared on the
+   * template are not yet applied to inherited subclass builders; subclasses currently use default
+   * options (see issue #248).
    *
    * <p>Example:
    *

From 218ea79ab5d1ddde6b83218112a5cedf44c56129 Mon Sep 17 00:00:00 2001
From: AndreasIgel <AndreasIgel82@gmail.com>
Date: Sat, 15 Aug 2026 18:16:47 +0200
Subject: [PATCH 10/11] Remove redundant troubleshooting item about
 @SimpleBuilder.Template target

The compiler and IDE already enforce @Target(ANNOTATION_TYPE) and show
a clear error when @SimpleBuilder.Template is placed on a class/record,
so this troubleshooting item adds no value.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 docs/CONFIGURATION.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index ce56e05a..f3dc39e2 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -1157,9 +1157,8 @@ Or in compiler options:
 2. **Verify options parameter**: Template must specify `options = @SimpleBuilder.Options(...)`
 3. **Retention and Target**: Add `@Retention(RetentionPolicy.CLASS)` and `@Target(ElementType.TYPE)`
 4. **Don't combine**: Don't use `@SimpleBuilder` when using a template annotation
-5. **Not a class annotation**: `@SimpleBuilder.Template` can only be placed on an annotation declaration (`@interface`), not directly on a class or record. Use `@SimpleBuilder` for direct class/record annotation, or create a custom annotation with `@SimpleBuilder.Template` and place that on the class.
-6. **Subclasses not getting a builder**: Add `@Inherited` to the custom template annotation so it propagates to unannotated subclasses (see [Template Annotations](#template-annotations) above). Without `@Inherited`, only the exact type carrying the annotation gets a builder.
-7. **Subclass builder has wrong options**: Inherited subclass builders currently use default options, not the parent's `@SimpleBuilder.Options` or template options. This is a known limitation (see #248).
+5. **Subclasses not getting a builder**: Add `@Inherited` to the custom template annotation so it propagates to unannotated subclasses (see [Template Annotations](#template-annotations) above). Without `@Inherited`, only the exact type carrying the annotation gets a builder.
+6. **Subclass builder has wrong options**: Inherited subclass builders currently use default options, not the parent's `@SimpleBuilder.Options` or template options. This is a known limitation (see #248).
 
 ### Builder Not Generated - Access Modifier Errors
 

From b20b5d861e2c7af0fb24aa2af27eaee27a075b10 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sun, 16 Aug 2026 21:24:46 +0000
Subject: [PATCH 11/11] refactor: make @SimpleBuilder a built-in template
 annotation (#246)

Co-Authored-By: Andreas Igel <andreas.igel@computacenter.com>
---
 .../core/annotations/SimpleBuilder.java       |  16 +-
 docs/CONFIGURATION.md                         |   6 +-
 .../builders/processor/BuilderProcessor.java  |  32 +-
 .../BuilderConfigurationReader.java           | 318 ++++++++----------
 .../BuilderAnnotationInheritanceTest.java     |  78 +++++
 .../BuilderConfigurationReaderTest.java       |  26 +-
 .../processor/BuilderProcessorTest.java       |   2 +-
 7 files changed, 259 insertions(+), 219 deletions(-)

diff --git a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
index 488bcb10..0a9d5b16 100644
--- a/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
+++ b/core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java
@@ -63,7 +63,15 @@
  *   <li><b>Integration:</b> generateWithInterface (default: true)
  * </ul>
  *
- * <p>Use {@link Template} to create reusable configuration presets.
+ * <p>This annotation is itself a built-in {@link Template}: it is meta-annotated with
+ * {@code @SimpleBuilder.Template(options = @Options())}. When placed on a class or record, the
+ * processor treats it like any other template annotation. The optional {@link #options()} attribute
+ * on a concrete {@code @SimpleBuilder} usage overrides the template defaults.
+ *
+ * <p>Use {@link Template} to create reusable configuration presets for project- or layer-specific
+ * conventions. A custom template annotation is an annotation type that is itself meta-annotated
+ * with {@code @SimpleBuilder.Template(options = @SimpleBuilder.Options(...))} and then applied to
+ * classes and records.
  *
  * <p>This annotation is {@link Inherited}: a subclass of an annotated type is treated as if it also
  * carried {@code @SimpleBuilder} for the purpose of triggering builder generation, unless it is
@@ -89,6 +97,7 @@
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.CLASS)
 @Inherited
+@SimpleBuilder.Template
 public @interface SimpleBuilder {
 
   /**
@@ -782,10 +791,11 @@
   @Inherited
   @interface Template {
     /**
-     * The options to apply when this template is used.
+     * The options to apply when this template is used. Defaults to an empty {@link Options}
+     * instance, so templates inherit the built-in defaults unless options are explicitly set.
      *
      * @return the builder configuration options
      */
-    Options options();
+    Options options() default @Options();
   }
 }
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 0579421b..01a0ca35 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -80,7 +80,7 @@ public class PersonDto {
 
 ## Template Annotations
 
-`@SimpleBuilder.Template` is a **meta-annotation**: it is placed on a custom annotation declaration (`@interface`), not directly on a class or record. Use it to create reusable configuration presets that can be applied to many classes with a single custom annotation. For one-off builder generation, use `@SimpleBuilder` directly on the class.
+`@SimpleBuilder.Template` is a **meta-annotation**: it is placed on a custom annotation declaration (`@interface`), not directly on a class or record. Use it to create reusable configuration presets that can be applied to many classes with a single custom annotation. `@SimpleBuilder` itself is the built-in template: it is meta-annotated with `@SimpleBuilder.Template` and can be used directly on a class for one-off builder generation, or you can define your own custom template annotations.
 
 | Need | Use |
 |------|-----|
@@ -1154,9 +1154,9 @@ Or in compiler options:
 ### Template Annotations Not Working
 
 1. **Check @SimpleBuilder.Template**: Ensure template annotation has `@SimpleBuilder.Template`
-2. **Verify options parameter**: Template must specify `options = @SimpleBuilder.Options(...)`
+2. **Verify options parameter**: Template can specify `options = @SimpleBuilder.Options(...)` or rely on the built-in defaults (omitting it is equivalent to an empty `@Options()`)
 3. **Retention and Target**: Add `@Retention(RetentionPolicy.CLASS)` and `@Target(ElementType.TYPE)`
-4. **Don't combine**: Don't use `@SimpleBuilder` when using a template annotation
+4. **Combining with @SimpleBuilder**: `@SimpleBuilder` is itself a built-in template. If both `@SimpleBuilder` and a custom template are present on the same class, `@SimpleBuilder` takes precedence in that scope. To use a custom template, place only the custom annotation on the class.
 5. **Subclasses not getting a builder**: Add `@Inherited` to the custom template annotation so it propagates to unannotated subclasses (see [Template Annotations](#template-annotations) above). Without `@Inherited`, only the exact type carrying the annotation gets a builder.
 6. **Subclass builder has wrong options**: Ensure the custom template annotation is `@Inherited` and that the parent annotation declares the desired `@SimpleBuilder.Options`. Inherited options are applied to subclass builders; a subclass's own annotation overrides the inherited options.
 
diff --git a/processor/src/main/java/org/javahelpers/simple/builders/processor/BuilderProcessor.java b/processor/src/main/java/org/javahelpers/simple/builders/processor/BuilderProcessor.java
index 5efaf2bd..d89d43e1 100644
--- a/processor/src/main/java/org/javahelpers/simple/builders/processor/BuilderProcessor.java
+++ b/processor/src/main/java/org/javahelpers/simple/builders/processor/BuilderProcessor.java
@@ -44,7 +44,6 @@
 import javax.lang.model.element.Element;
 import javax.lang.model.element.TypeElement;
 import org.javahelpers.simple.builders.core.annotations.Ignore4BuilderGeneration;
-import org.javahelpers.simple.builders.core.annotations.SimpleBuilder;
 import org.javahelpers.simple.builders.core.annotations.SimpleBuilder.Template;
 import org.javahelpers.simple.builders.processor.analysis.JavaLangAnalyser;
 import org.javahelpers.simple.builders.processor.classgen.roaster.RoasterCodeGenerator;
@@ -135,20 +134,14 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
 
     BuilderConfigurationReader reader = context.getConfigurationReader();
 
-    // Find all elements to process:
-    // 1. Elements annotated with @SimpleBuilder
-    // 2. Elements annotated with custom annotations that have @SimpleBuilder.Template
-    // Configuration is resolved per-element to handle priority correctly when both exist
+    // Find all elements to process: any element annotated with an annotation that is
+    // meta-annotated with @SimpleBuilder.Template. This includes @SimpleBuilder itself, which is
+    // a built-in template. Configuration is resolved per-element to handle priority correctly.
     Set<Element> elementsToProcess = new HashSet<>();
 
-    // Find all @SimpleBuilder annotations
-    TypeElement simpleBuilderAnnotation =
-        context.getTypeElement(SimpleBuilder.class.getCanonicalName());
-    if (simpleBuilderAnnotation != null) {
-      elementsToProcess.addAll(roundEnv.getElementsAnnotatedWith(simpleBuilderAnnotation));
-    }
-
-    // Find all Annotations with @SimpleBuilder.Template
+    // Find all annotations meta-annotated with @SimpleBuilder.Template (this includes
+    // @SimpleBuilder itself, which is now a built-in template). Each such annotation triggers
+    // builder generation for the elements it is applied to.
     List<TypeElement> annotationsWithTemplate = extractingAnnotationsWithTemplate(annotations);
     for (TypeElement annotation : annotationsWithTemplate) {
       elementsToProcess.addAll(roundEnv.getElementsAnnotatedWith(annotation));
@@ -279,15 +272,8 @@ private static List<TypeElement> extractingAnnotationsWithTemplate(
   }
 
   private static boolean shouldSkipAnnotation(TypeElement annotation) {
-    // Only process real annotation specifications
-    if (annotation.getKind() != javax.lang.model.element.ElementKind.ANNOTATION_TYPE) {
-      return true;
-    }
-    // Skip @SimpleBuilder annotation because we only want to find annotations with
-    // @SimpleBuilder.Template
-    return annotation
-        .getQualifiedName()
-        .toString()
-        .equals(org.javahelpers.simple.builders.core.annotations.SimpleBuilder.class.getName());
+    // Only process real annotation specifications. @SimpleBuilder is now a built-in template, so
+    // it is processed through the same path as custom template annotations.
+    return annotation.getKind() != javax.lang.model.element.ElementKind.ANNOTATION_TYPE;
   }
 }
diff --git a/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/BuilderConfigurationReader.java b/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/BuilderConfigurationReader.java
index 1711d768..6abb5259 100644
--- a/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/BuilderConfigurationReader.java
+++ b/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/BuilderConfigurationReader.java
@@ -33,8 +33,8 @@
 import javax.lang.model.element.AnnotationValue;
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
+import javax.lang.model.element.TypeElement;
 import javax.lang.model.util.Elements;
-import org.javahelpers.simple.builders.core.annotations.SimpleBuilder;
 import org.javahelpers.simple.builders.core.enums.AccessModifier;
 import org.javahelpers.simple.builders.core.enums.OptionState;
 import org.javahelpers.simple.builders.processor.exceptions.BuilderException;
@@ -43,23 +43,26 @@
 /**
  * Reads builder configuration from annotated elements.
  *
- * <p>This class analyzes {@link SimpleBuilder.Options} and custom template annotations (annotations
- * meta-annotated with {@link SimpleBuilder.Template}) on an element.
+ * <p>Both {@code @SimpleBuilder} and custom annotations are treated as template annotations: an
+ * annotation triggers builder generation when it is itself meta-annotated with
+ * {@code @SimpleBuilder.Template}. {@code @SimpleBuilder} is the built-in template; its optional
+ * {@code options()} attribute overrides the defaults declared on its own
+ * {@code @SimpleBuilder.Template} meta-annotation. Custom template annotations carry their
+ * configuration on the {@code @SimpleBuilder.Template} meta-annotation.
  *
  * <p>Priority order (highest to lowest):
  *
  * <ol>
- *   <li>Directly declared {@code @SimpleBuilder(options = ...)} inline options
- *   <li>Custom template annotations directly declared on the element
- *   <li>Inherited {@code @SimpleBuilder(options = ...)} inline options
- *   <li>Inherited custom template annotations
+ *   <li>Directly declared template annotations on the element (with {@code @SimpleBuilder} taking
+ *       precedence over other direct templates in the same scope)
+ *   <li>Inherited template annotations
  *   <li>Global compiler arguments
  *   <li>Built-in defaults
  * </ol>
  *
  * <p>Custom template annotations are annotations that are themselves meta-annotated with
- * {@code @SimpleBuilder.Template}; they are not placed directly on the class. Within each
- * inheritance scope, {@code @SimpleBuilder} options take precedence over template options.
+ * {@code @SimpleBuilder.Template}; they are placed directly on the class or record. Direct
+ * annotations always override inherited annotations.
  */
 public class BuilderConfigurationReader {
   private static final String SIMPLE_BUILDER_ANNOTATION =
@@ -97,34 +100,124 @@ public BuilderConfiguration getGlobalConfiguration() {
   }
 
   /**
-   * Reads builder configuration from {@code @SimpleBuilder(options = ...)} inline options.
+   * Resolves the complete builder configuration for an element by chaining all configuration
+   * sources in priority order.
    *
-   * <p>Directly declared options take precedence over inherited options from superclasses.
+   * <p>Priority chain (highest to lowest):
    *
-   * <p>Returns null if the element has no {@code @SimpleBuilder} annotation.
+   * <ol>
+   *   <li>Direct template annotations on the element
+   *   <li>Inherited template annotations
+   *   <li>Global compiler arguments
+   *   <li>Built-in defaults
+   * </ol>
    *
-   * @param element the annotated element to analyze
-   * @return configuration from the inline options, or null if not present
+   * <p>When both {@code @SimpleBuilder} and another direct template annotation are present on the
+   * same element, {@code @SimpleBuilder} takes precedence within that scope. A subclass's own
+   * annotation always overrides inherited annotations.
+   *
+   * @param element the annotated element to resolve configuration for
+   * @return the fully resolved configuration with all sources merged
    */
-  public BuilderConfiguration readFromInlineOptions(Element element) {
-    BuilderConfiguration direct = readFromInlineOptions(element, AnnotationScope.DIRECT);
-    if (direct != null) {
-      return direct;
+  public BuilderConfiguration resolveConfiguration(Element element) throws BuilderException {
+    String elementName = element.getSimpleName().toString();
+    logger.debugStartOperation("Resolving configuration for element: %s", elementName);
+
+    BuilderConfiguration inheritedConfig = readFromScope(element, AnnotationScope.INHERITED);
+    BuilderConfiguration directConfig = readFromScope(element, AnnotationScope.DIRECT);
+
+    BuilderConfiguration result =
+        BuilderConfiguration.DEFAULT
+            .merge(globalConfiguration)
+            .merge(inheritedConfig)
+            .merge(directConfig);
+
+    // Validate access modifiers and warn about problematic configurations
+    validateAccessModifiers(element, result);
+
+    logger.debugEndOperation("Resulting configuration resolved: %s", result.toString());
+    return result;
+  }
+
+  /**
+   * Reads the highest-priority template configuration for the element in the requested scope.
+   *
+   * <p>If {@code @SimpleBuilder} is present in the scope, its effective configuration (built-in
+   * template defaults overridden by any inline {@code options()}) is returned. Otherwise the first
+   * custom template annotation found in the scope is used.
+   */
+  private BuilderConfiguration readFromScope(Element element, AnnotationScope scope) {
+    List<? extends AnnotationMirror> mirrors = getAnnotationMirrors(element, scope);
+    BuilderConfiguration simpleBuilderConfig = null;
+    BuilderConfiguration customTemplateConfig = null;
+
+    for (AnnotationMirror mirror : mirrors) {
+      if (isSimpleBuilderAnnotation(mirror)) {
+        simpleBuilderConfig = extractSimpleBuilderConfiguration(mirror);
+      } else if (customTemplateConfig == null) {
+        BuilderConfiguration templateConfig = extractCustomTemplateConfiguration(mirror);
+        if (templateConfig != null) {
+          logger.debug(
+              "Annotation based Configuration for scope %s: %s", scope, templateConfig.toString());
+          customTemplateConfig = templateConfig;
+        }
+      }
     }
-    return readFromInlineOptions(element, AnnotationScope.INHERITED);
+
+    if (simpleBuilderConfig != null) {
+      logger.debug("Built-in template @SimpleBuilder found in %s scope", scope);
+      return simpleBuilderConfig;
+    }
+    return customTemplateConfig;
+  }
+
+  /**
+   * Extracts the effective configuration for a concrete {@code @SimpleBuilder} usage. The built-in
+   * template defaults defined on the {@code @SimpleBuilder} annotation type are merged with the
+   * inline {@code options()} from the usage, so inline options override the template defaults.
+   */
+  private BuilderConfiguration extractSimpleBuilderConfiguration(
+      AnnotationMirror simpleBuilderMirror) {
+    TypeElement simpleBuilderType =
+        (TypeElement) simpleBuilderMirror.getAnnotationType().asElement();
+    BuilderConfiguration templateDefaults = extractTemplateConfigurationFromType(simpleBuilderType);
+    BuilderConfiguration inlineOptions = extractOptionsFromAnnotationMirror(simpleBuilderMirror);
+    return mergeNullable(templateDefaults, inlineOptions);
+  }
+
+  /**
+   * Extracts the configuration for a custom template annotation usage. The configuration is read
+   * from the {@code @SimpleBuilder.Template} meta-annotation on the custom annotation type.
+   */
+  private BuilderConfiguration extractCustomTemplateConfiguration(
+      AnnotationMirror annotationMirror) {
+    TypeElement annotationType = (TypeElement) annotationMirror.getAnnotationType().asElement();
+    return extractTemplateConfigurationFromType(annotationType);
   }
 
-  private BuilderConfiguration readFromInlineOptions(Element element, AnnotationScope scope) {
-    AnnotationMirror simpleBuilderMirror =
-        extractAnnotationMirror(element, SIMPLE_BUILDER_ANNOTATION, scope);
-    return extractOptionsFromAnnotationMirror(simpleBuilderMirror);
+  /**
+   * Extracts the template configuration declared on an annotation type by reading the {@code
+   * options} attribute of its {@code @SimpleBuilder.Template} meta-annotation.
+   *
+   * @return the configuration, or {@code null} if the type is not a template annotation
+   */
+  private BuilderConfiguration extractTemplateConfigurationFromType(TypeElement annotationType) {
+    AnnotationMirror templateMetaMirror = findTemplateMetaMirror(annotationType);
+    if (templateMetaMirror == null) {
+      return null;
+    }
+    return extractOptionsFromAnnotationMirror(templateMetaMirror);
   }
 
-  private AnnotationMirror extractAnnotationMirror(
-      Element element, String annotationName, AnnotationScope scope) {
-    for (AnnotationMirror mirror : getAnnotationMirrors(element, scope)) {
-      if (mirror.getAnnotationType().toString().equals(annotationName)) {
-        return mirror;
+  /**
+   * Finds the {@code @SimpleBuilder.Template} meta-annotation on an annotation type.
+   *
+   * @return the template meta-annotation mirror, or {@code null} if not present
+   */
+  private AnnotationMirror findTemplateMetaMirror(TypeElement annotationType) {
+    for (AnnotationMirror metaMirror : annotationType.getAnnotationMirrors()) {
+      if (isTemplateAnnotation(metaMirror)) {
+        return metaMirror;
       }
     }
     return null;
@@ -132,10 +225,11 @@ private AnnotationMirror extractAnnotationMirror(
 
   /**
    * Extracts configuration from the 'options' attribute of an annotation mirror. Used for
-   * inline @SimpleBuilder(options = ...) where reflection doesn't work.
+   * {@code @SimpleBuilder(options = ...)} and for {@code @SimpleBuilder.Template(options = ...)}.
    *
    * @param annotationMirror the annotation mirror (either @SimpleBuilder or @Template)
-   * @return the configuration extracted from the options attribute
+   * @return the configuration extracted from the options attribute, or {@code null} if no options
+   *     are set
    */
   private BuilderConfiguration extractOptionsFromAnnotationMirror(
       AnnotationMirror annotationMirror) {
@@ -143,10 +237,11 @@ private BuilderConfiguration extractOptionsFromAnnotationMirror(
       return null;
     }
 
-    // Find the 'options' attribute
+    // Find the 'options' attribute, including default values. This is important for @SimpleBuilder,
+    // whose options() attribute defaults to @Options() even when it is not explicitly specified.
     AnnotationMirror optionsMirror = null;
     Map<? extends ExecutableElement, ? extends AnnotationValue> elementValues =
-        annotationMirror.getElementValues();
+        elementUtils.getElementValuesWithDefaults(annotationMirror);
 
     for (Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry :
         elementValues.entrySet()) {
@@ -168,6 +263,18 @@ private BuilderConfiguration extractOptionsFromAnnotationMirror(
     return parseOptionsFromMirror(optionsMirror);
   }
 
+  /** Merges two nullable configurations, preferring the override when both are present. */
+  private BuilderConfiguration mergeNullable(
+      BuilderConfiguration base, BuilderConfiguration override) {
+    if (base == null) {
+      return override;
+    }
+    if (override == null) {
+      return base;
+    }
+    return base.merge(override);
+  }
+
   /**
    * Parses SimpleBuilder.Options from AnnotationMirror. Only contains explicitly set values (not
    * defaults).
@@ -243,48 +350,6 @@ private String extractEnumName(Object value) {
         : enumString;
   }
 
-  /**
-   * Reads builder configuration from a custom template annotation on the element.
-   *
-   * <p>Directly declared template annotations take precedence over inherited template annotations.
-   * If a {@code @SimpleBuilder} annotation is present in the same scope, template annotations in
-   * that scope are ignored.
-   *
-   * <p>Returns null if no template annotation is found or if {@code @SimpleBuilder} is present.
-   *
-   * @param element the annotated element to analyze
-   * @return configuration from the template annotation, or null if not present
-   */
-  public BuilderConfiguration readFromTemplate(Element element) {
-    BuilderConfiguration direct = readFromTemplate(element, AnnotationScope.DIRECT);
-    if (direct != null) {
-      return direct;
-    }
-    return readFromTemplate(element, AnnotationScope.INHERITED);
-  }
-
-  private BuilderConfiguration readFromTemplate(Element element, AnnotationScope scope) {
-    List<? extends AnnotationMirror> mirrors = getAnnotationMirrors(element, scope);
-
-    // If @SimpleBuilder is present in this scope, ignore template annotations in the same scope
-    if (containsSimpleBuilder(mirrors)) {
-      logger.debug(
-          "Template annotations ignored because @SimpleBuilder is present in %s scope", scope);
-      return null;
-    }
-
-    // Check all annotations in this scope to find one annotated with @SimpleBuilder.Template
-    for (AnnotationMirror mirror : mirrors) {
-      BuilderConfiguration templateConfig = checkForTemplateAnnotation(mirror, element);
-      if (templateConfig != null) {
-        logger.debug("Annotation based Configuration: %s", templateConfig.toString());
-        return templateConfig;
-      }
-    }
-
-    return null;
-  }
-
   private enum AnnotationScope {
     DIRECT,
     INHERITED
@@ -310,17 +375,8 @@ private List<? extends AnnotationMirror> getAnnotationMirrors(
     return inheritedMirrors;
   }
 
-  private boolean containsSimpleBuilder(List<? extends AnnotationMirror> mirrors) {
-    for (AnnotationMirror mirror : mirrors) {
-      if (isSimpleBuilderAnnotation(mirror)) {
-        return true;
-      }
-    }
-    return false;
-  }
-
   /**
-   * Checks if an annotation mirror represents @SimpleBuilder.
+   * Checks whether an annotation mirror represents @SimpleBuilder.
    *
    * @param mirror the annotation mirror to check
    * @return true if this is @SimpleBuilder
@@ -330,29 +386,6 @@ private boolean isSimpleBuilderAnnotation(AnnotationMirror mirror) {
     return typeName.equals(SIMPLE_BUILDER_ANNOTATION);
   }
 
-  /**
-   * Checks if an annotation is a template annotation and extracts its configuration.
-   *
-   * @param mirror the annotation mirror to check
-   * @param element the element being processed (for logging)
-   * @return the configuration if this is a template annotation, null otherwise
-   */
-  private BuilderConfiguration checkForTemplateAnnotation(
-      AnnotationMirror mirror, Element element) {
-    Element annotationElement = mirror.getAnnotationType().asElement();
-
-    // Check using AnnotationMirror for template annotations
-    for (AnnotationMirror metaMirror : annotationElement.getAnnotationMirrors()) {
-      if (isTemplateAnnotation(metaMirror)) {
-        logger.debug(
-            "Found template annotation '%s' on '%s'",
-            annotationElement.getSimpleName(), element.getSimpleName());
-        return extractOptionsFromTemplateMirror(metaMirror);
-      }
-    }
-    return null;
-  }
-
   /**
    * Checks if an annotation mirror represents @SimpleBuilder.Template.
    *
@@ -366,77 +399,6 @@ private boolean isTemplateAnnotation(AnnotationMirror metaMirror) {
         || metaAnnotationName.equals(SIMPLE_BUILDER_TEMPLATE_ANNOTATION_ALT);
   }
 
-  /**
-   * Extracts configuration from @SimpleBuilder.Template(options = ...) using AnnotationMirror.
-   * Fallback for same-round compiled templates where reflection doesn't work.
-   */
-  private BuilderConfiguration extractOptionsFromTemplateMirror(AnnotationMirror templateMirror) {
-    Map<? extends ExecutableElement, ? extends AnnotationValue> templateValues =
-        elementUtils.getElementValuesWithDefaults(templateMirror);
-
-    for (Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry :
-        templateValues.entrySet()) {
-      if (entry.getKey().getSimpleName().toString().equals("options")) {
-        Object value = entry.getValue().getValue();
-        if (value instanceof AnnotationMirror optionsMirror) {
-          return parseOptionsFromMirror(optionsMirror);
-        }
-      }
-    }
-    return null;
-  }
-
-  /**
-   * Resolves the complete builder configuration for an element by chaining all configuration
-   * sources in priority order.
-   *
-   * <p>Priority chain (highest to lowest):
-   *
-   * <ol>
-   *   <li>Directly declared {@code @SimpleBuilder(options = ...)} inline options
-   *   <li>Custom template annotations directly declared on the element
-   *   <li>Inherited {@code @SimpleBuilder(options = ...)} inline options
-   *   <li>Inherited custom template annotations
-   *   <li>Global compiler arguments
-   *   <li>Built-in defaults
-   * </ol>
-   *
-   * <p>Custom template annotations are annotations that are themselves meta-annotated with
-   * {@code @SimpleBuilder.Template} and are placed directly on the class; the
-   * {@code @SimpleBuilder.Template} meta-annotation is not placed on the class itself. Within each
-   * inheritance scope, {@code @SimpleBuilder} options take precedence over template options. Direct
-   * annotations always override inherited annotations.
-   *
-   * @param element the annotated element to resolve configuration for
-   * @return the fully resolved configuration with all sources merged
-   */
-  public BuilderConfiguration resolveConfiguration(Element element) throws BuilderException {
-    String elementName = element.getSimpleName().toString();
-    logger.debugStartOperation("Resolving configuration for element: %s", elementName);
-
-    BuilderConfiguration inheritedTemplateConfig =
-        readFromTemplate(element, AnnotationScope.INHERITED);
-    BuilderConfiguration inheritedInlineConfig =
-        readFromInlineOptions(element, AnnotationScope.INHERITED);
-    BuilderConfiguration directTemplateConfig = readFromTemplate(element, AnnotationScope.DIRECT);
-    BuilderConfiguration directInlineConfig =
-        readFromInlineOptions(element, AnnotationScope.DIRECT);
-
-    BuilderConfiguration result =
-        BuilderConfiguration.DEFAULT
-            .merge(globalConfiguration)
-            .merge(inheritedTemplateConfig)
-            .merge(inheritedInlineConfig)
-            .merge(directTemplateConfig)
-            .merge(directInlineConfig);
-
-    // Validate access modifiers and warn about problematic configurations
-    validateAccessModifiers(element, result);
-
-    logger.debugEndOperation("Resulting configuration resolved: %s", result.toString());
-    return result;
-  }
-
   /**
    * Validates access modifier configurations and throws exception for invalid settings.
    *
diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java
index 33e4ef44..5210b161 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderAnnotationInheritanceTest.java
@@ -592,4 +592,82 @@ public class ChildDto extends ParentDto {
     assertNotContaining(childBuilder, "Supplier<");
     assertNotContaining(childBuilder, "Consumer<");
   }
+
+  /**
+   * A direct {@code @SimpleBuilder} on a subclass must override an inherited custom template
+   * annotation. This proves that {@code @SimpleBuilder} is handled through the same template
+   * discovery path as custom templates and wins within the same scope by precedence.
+   */
+  @Test
+  void directSimpleBuilderOverridesInheritedCustomTemplateOptions() {
+    JavaFileObject parentTemplate =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            import java.lang.annotation.ElementType;
+            import java.lang.annotation.Inherited;
+            import java.lang.annotation.Retention;
+            import java.lang.annotation.RetentionPolicy;
+            import java.lang.annotation.Target;
+            import org.javahelpers.simple.builders.core.annotations.SimpleBuilder;
+            import org.javahelpers.simple.builders.core.enums.OptionState;
+
+            @SimpleBuilder.Template(options = @SimpleBuilder.Options(
+                generateFieldSupplier = OptionState.DISABLED,
+                builderSuffix = "ParentBuilder"
+            ))
+            @Inherited
+            @Retention(RetentionPolicy.CLASS)
+            @Target(ElementType.TYPE)
+            public @interface ParentTemplate {}
+            """);
+
+    JavaFileObject parentSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            @ParentTemplate
+            public class ParentDto {
+                private String name;
+
+                public String getName() { return name; }
+                public void setName(String name) { this.name = name; }
+            }
+            """);
+
+    JavaFileObject childSource =
+        ProcessorTestUtils.forSource(
+            """
+            package test;
+
+            import org.javahelpers.simple.builders.core.annotations.SimpleBuilder;
+
+            @SimpleBuilder(options = @SimpleBuilder.Options(
+                builderSuffix = "ChildBuilder"
+            ))
+            public class ChildDto extends ParentDto {
+                private int age;
+
+                public int getAge() { return age; }
+                public void setAge(int age) { this.age = age; }
+            }
+            """);
+
+    Compilation compilation = compile(parentTemplate, parentSource, childSource);
+
+    assertThat(compilation).succeededWithoutWarnings();
+
+    String parentBuilder = loadGeneratedSource(compilation, "ParentDtoParentBuilder");
+    assertContaining(parentBuilder, "class ParentDtoParentBuilder");
+    assertContaining(parentBuilder, "public ParentDtoParentBuilder name(String name)");
+    assertNotContaining(parentBuilder, "Supplier<");
+
+    String childBuilder = loadGeneratedSource(compilation, "ChildDtoChildBuilder");
+    assertContaining(childBuilder, "class ChildDtoChildBuilder");
+    assertContaining(childBuilder, "public ChildDtoChildBuilder name(String name)");
+    assertContaining(childBuilder, "public ChildDtoChildBuilder age(int age)");
+    assertNotContaining(childBuilder, "Supplier<");
+  }
 }
diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderConfigurationReaderTest.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderConfigurationReaderTest.java
index 80ddcc7c..18993690 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderConfigurationReaderTest.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderConfigurationReaderTest.java
@@ -34,13 +34,16 @@
 
 /**
  * Integration tests for {@link
- * org.javahelpers.simple.builders.processor.util.BuilderConfigurationReader}.
+ * org.javahelpers.simple.builders.processor.processing.BuilderConfigurationReader}.
  *
- * <p>Verifies configuration reading from various sources through end-to-end compilation:
+ * <p>Verifies configuration reading from various sources through end-to-end compilation. Both
+ * {@code @SimpleBuilder} (which is itself a built-in {@code @SimpleBuilder.Template}) and custom
+ * template annotations are discovered and resolved through the same path.
  *
  * <ul>
  *   <li>Direct {@code @SimpleBuilder.Options} annotations
- *   <li>Template annotations ({@code @SimpleBuilder.Template})
+ *   <li>Template annotations ({@code @SimpleBuilder.Template}), including the built-in
+ *       {@code @SimpleBuilder}
  *   <li>Configuration resolution with proper priority chain
  *   <li>Compiler arguments
  * </ul>
@@ -53,8 +56,8 @@ class BuilderConfigurationReaderTest {
   /**
    * Test: Builder respects configuration from @SimpleBuilder.Options annotation.
    *
-   * <p>Verifies BuilderConfigurationReader.readFromOptions() correctly reads and applies all
-   * options.
+   * <p>Verifies the built-in {@code @SimpleBuilder} template is resolved and its inline {@code
+   * options()} override the template defaults.
    */
   @Test
   void readFromOptions_WithOptionsAnnotation_AppliesAllOptions() {
@@ -134,10 +137,10 @@ public class PersonDto {
   }
 
   /**
-   * Test: Builder respects configuration from template annotation.
+   * Test: Builder respects configuration from a custom template annotation.
    *
-   * <p>Verifies BuilderConfigurationReader.readFromTemplate() correctly detects and applies
-   * template configuration.
+   * <p>Verifies a custom annotation meta-annotated with {@code @SimpleBuilder.Template} is resolved
+   * through the same path as the built-in {@code @SimpleBuilder}.
    */
   @Test
   void readFromTemplate_WithTemplateAnnotation_AppliesTemplateConfiguration() {
@@ -244,10 +247,11 @@ class PersonDto {
   }
 
   /**
-   * Test: Options annotation overrides template annotation (proper priority).
+   * Test: Inline @SimpleBuilder options override a custom template annotation.
    *
-   * <p>Verifies BuilderConfigurationReader.resolveConfiguration() applies correct priority: Options
-   * > Template > Compiler args > Defaults
+   * <p>Verifies resolveConfiguration() applies correct priority when both the built-in
+   * {@code @SimpleBuilder} and a custom template are present: direct {@code @SimpleBuilder} options
+   * win over the custom template, which in turn wins over compiler arguments and defaults.
    */
   @Test
   void resolveConfiguration_OptionsOverridesTemplate_AppliesPriorityCorrectly() {
diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderProcessorTest.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderProcessorTest.java
index 4a2daf22..568301ab 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderProcessorTest.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/BuilderProcessorTest.java
@@ -98,7 +98,7 @@ void shouldLogDebugMessagesWhenVerboseModeEnabled() {
         "[DEBUG] simple-builders: Processing round started. Found 1 annotated elements.",
         "[DEBUG] Processing element: VerboseTest",
         "[DEBUG] ├─ Resolving configuration for element: VerboseTest",
-        "[DEBUG] │  ├─ Template annotations ignored because @SimpleBuilder is present in DIRECT scope",
+        "[DEBUG] │  ├─ Built-in template @SimpleBuilder found in DIRECT scope",
         "[DEBUG] │  └─ Resulting configuration resolved: BuilderConfiguration[",
         "[DEBUG] ├─ Extracting builder definition from: test.VerboseTest",
         "[DEBUG] │  ├─ Builder will be generated as: test.VerboseTestBuilder",