abapgit-agent 1.15.0 → 1.15.2

package/abap/CLAUDE.md

@@ -1,11 +1,11 @@
 ---
 layout: default
-title: Claude Code Instructions (Template)
+title: AI Agent Instructions
 nav_order: 1
 parent: ABAP Development
 ---
 
-# Claude Code Instructions - Template
+# AI Agent Instructions
 
 This file provides guidelines for **generating ABAP code** in abapGit repositories.
 
@@ -157,10 +157,11 @@ Anything else (SAP namespace object, or SAP-delivered package)?
 ```
 
 > **Tip for project setup**: Add package rules to `objects.local.md` so Claude never
-> needs to ask. See `guidelines/objects.md` for examples.
+> needs to ask. Run: `abapgit-agent ref --topic objects`
 
 → For exact XML templates: `abapgit-agent ref --topic abapgit` (CLAS/INTF/PROG/DDLS/DCLS/FUGR) or `abapgit-agent ref --topic abapgit-xml-only` (TABL/STRU/DTEL/TTYP/DOMA/MSAG)
 → For local helper/test-double class files: `abapgit-agent ref --topic object-creation`
+→ For documentation comment format (shorttext, @parameter, CDS): `abapgit-agent ref --topic comments`
 
 ---
 
@@ -213,9 +214,15 @@ abapgit-agent pull --files src/<intf_name>.intf.abap,src/<class_name>.clas.abap
 
 ### 5. Local Helper / Test-Double Classes
 
-→ See `guidelines/object-creation.md` — run: `abapgit-agent ref --topic object-creation`
+When a class needs local helper classes or test doubles, create separate include files alongside the main class file:
 
-**XML metadata when adding test classes:**
+```
+<name>.clas.locals_def.abap   ← local type/class definitions
+<name>.clas.locals_imp.abap   ← local class implementations
+<name>.clas.testclasses.abap  ← unit test classes (FOR TESTING)
+```
+
+**XML metadata when adding these files:**
 
 ```
 Adding .clas.testclasses.abap to an existing class?
@@ -228,6 +235,7 @@ Adding .clas.locals_def.abap (local type definitions)?
         <CLSCCINCL>X</CLSCCINCL>
 ```
 
+→ For exact XML flag placement and test double class patterns: `abapgit-agent ref --topic object-creation`
 → For exact XML flag placement: `abapgit-agent ref --topic abapgit` (search "WITH_UNIT_TESTS")
 
 ---
@@ -330,8 +338,11 @@ AI thought process:
 
 ### 7. CDS Unit Tests
 
-Use `CL_CDS_TEST_ENVIRONMENT` for unit tests that read CDS views.
-→ See `guidelines/cds-testing.md` — run: `abapgit-agent ref --topic cds-testing`
+If a class under test reads a CDS view, use `CL_CDS_TEST_ENVIRONMENT` to provide test data — do **not** mock the database layer manually. Without this, test data setup is unreliable and tests may pass locally but fail on other systems.
+
+**Trigger**: your class calls `SELECT FROM <cds_view>` directly or via a helper.
+
+→ For full setup pattern and test double configuration: `abapgit-agent ref --topic cds-testing`
 
 ---
 
@@ -369,10 +380,7 @@ DATA(lo_cut) = NEW zcl_my_class( io_agent = lo_agent ).
 DATA(ls_actual) = lo_cut->execute( ).
 ```
 
-→ Full API reference (EXPORT params, exceptions, inherited methods, common mistakes):
-  `abapgit-agent ref --topic unit-testable-code`
-
-→ For class design rules (constructor injection, interfaces for dependencies):
+→ For full API reference (EXPORT params, exceptions, inherited methods, common mistakes) and class design rules (constructor injection, interfaces for dependencies):
   `abapgit-agent ref --topic unit-testable-code`
 
 #### Running tests — use `unit` command
@@ -435,7 +443,7 @@ Never assume — wait for the user's answer before proceeding.
 | HTTP 500 / runtime crash (ST22) | `dump` | Error already occurred |
 | Wrong output, no crash | `debug` | Need to trace logic |
 
-→ See `guidelines/debug-dump.md` — run: `abapgit-agent ref --topic debug-dump`
+→ `abapgit-agent ref --topic debug-dump`
 
 **Critical rules for `debug` sessions:**
 
@@ -496,7 +504,7 @@ abapgit-agent debug vars --json
 abapgit-agent debug step --type continue --json     # 4. release
 ```
 
-→ See `guidelines/debug-session.md` — run: `abapgit-agent ref --topic debug-session`
+→ `abapgit-agent ref --topic debug-session`
 
 ---
 
@@ -546,7 +554,7 @@ Projects can add their own abaplint notes to `guidelines/abaplint-local.md` in t
 project repository. After running `abapgit-agent ref export`, the `ref` command
 surfaces both bundled and project-specific guidance together.
 
-→ See `guidelines/abaplint.md` — run: `abapgit-agent ref --topic abaplint`
+→ `abapgit-agent ref --topic abaplint`
 
 ---
 
@@ -600,7 +608,7 @@ git push origin feature/my-change --force-with-lease
 abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 ```
 
-→ See `guidelines/branch-workflow.md` — run: `abapgit-agent ref --topic branch-workflow`
+→ `abapgit-agent ref --topic branch-workflow`
 
 ### Trunk Workflow (`"mode": "trunk"`)
 
@@ -716,47 +724,38 @@ Modified ABAP files?
 ```
 
 → For creating new objects (what files to write): `abapgit-agent ref --topic object-creation`
-→ See `guidelines/workflow-detailed.md` — run: `abapgit-agent ref --topic workflow-detailed`
+→ For full workflow decision tree and error indicators: `abapgit-agent ref --topic workflow-detailed`
 
 ---
 
 ## Guidelines Index
 
-> **Note:** If the `guidelines/` folder doesn't exist in your repo, the `ref` command
-> automatically uses bundled guidelines from the package. Access them with:
-> ```bash
-> abapgit-agent ref --topic <topic>   # e.g. ref --topic sql
-> abapgit-agent ref "<pattern>"       # e.g. ref "SELECT"
-> ```
-
-Detailed guidelines are available in the `guidelines/` folder:
-
-| File | Topic |
-|------|-------|
-| `guidelines/index.md` | Overview and usage |
-| `guidelines/sql.md` | ABAP SQL Best Practices |
-| `guidelines/exceptions.md` | Exception Handling |
-| `guidelines/testing.md` | Unit Testing (including CDS) |
-| `guidelines/cds.md` | CDS Views |
-| `guidelines/classes.md` | ABAP Classes and Objects |
-| `guidelines/objects.md` | Object Naming Conventions (defaults) |
-| `guidelines/objects.local.md` | **Project** Naming Conventions — overrides `objects.md` (created by `init`, never overwritten) |
-| `guidelines/json.md` | JSON Handling |
-| `guidelines/abapgit.md` | abapGit XML Metadata Templates — CLAS, INTF, PROG, DDLS, DCLS, FUGR |
-| `guidelines/abapgit-xml-only.md` | abapGit XML Metadata Templates — XML-only objects (TABL, STRU, DTEL, TTYP, DOMA, MSAG) |
-| `guidelines/unit-testable-code.md` | Unit Testable Code Guidelines (Dependency Injection) |
-| `guidelines/common-errors.md` | Common ABAP Errors - Quick Fixes |
-| `guidelines/debug-session.md` | Debug Session Guide |
-| `guidelines/debug-dump.md` | Dump Analysis Guide |
-| `guidelines/run-probe-classes.md` | run Command — AI Guidelines (probe classes, scratchWorkspace) |
-| `guidelines/probe-poc.md` | Probe and PoC — Full Decision Flow |
-| `guidelines/branch-workflow.md` | Branch Workflow |
-| `guidelines/workflow-detailed.md` | Development Workflow (Detailed) |
-| `guidelines/object-creation.md` | Object Creation (XML metadata, local classes) |
-| `guidelines/cds-testing.md` | CDS Testing (Test Double Framework) |
-| `guidelines/abaplint.md` | abaplint Rule Guidelines (prefer_inline trap, safe patterns) |
-
-These guidelines are automatically searched by the `ref` command.
+| Command | Topic |
+|---------|-------|
+| `ref --topic sql` | ABAP SQL Best Practices |
+| `ref --topic exceptions` | Exception Handling |
+| `ref --topic classes` | ABAP Classes and Objects |
+| `ref --topic objects` | Object Naming Conventions (defaults) |
+| `ref --topic comments` | Documentation Comments (ABAP DOC, shorttext, @parameter, CDS `//`, program `*&---`) |
+| `ref --topic testing` | Unit Testing |
+| `ref --topic unit-testable-code` | Unit Testable Code (Dependency Injection) |
+| `ref --topic cds` | CDS Views |
+| `ref --topic cds-testing` | CDS Testing (Test Double Framework) |
+| `ref --topic json` | JSON Handling |
+| `ref --topic common-errors` | Common ABAP Errors - Quick Fixes |
+| `ref --topic abapgit` | abapGit XML Metadata — **use for CDS/DDLS XML**, also CLAS, INTF, PROG, DCLS, FUGR |
+| `ref --topic abapgit-xml-only` | abapGit XML Metadata — XML-only objects (TABL, STRU, DTEL, TTYP, DOMA, MSAG) |
+| `ref --topic abapgit-fugr` | abapGit XML Metadata — Function Group (FUGR) details |
+| `ref --topic abaplint` | abaplint Rule Guidelines (prefer_inline trap, safe patterns) |
+| `ref --topic debug-session` | Debug Session Guide |
+| `ref --topic debug-dump` | Dump Analysis Guide |
+| `ref --topic branch-workflow` | Branch Workflow |
+| `ref --topic workflow-detailed` | Development Workflow (Detailed) |
+| `ref --topic object-creation` | Object Creation (XML metadata, local classes) |
+| `ref --topic run-probe-classes` | run Command — AI Guidelines (probe classes, scratchWorkspace) |
+| `ref --topic probe-poc` | Probe and PoC — Full Decision Flow |
+
+> `objects.local.md` — **Project** Naming Conventions (created by `init`, never overwritten). Read directly from `guidelines/objects.local.md` — no ref topic.
 
 ---
 

package/abap/guidelines/abapgit-fugr.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: abapGit XML Metadata — Function Group (FUGR)
-nav_order: 11
+nav_order: 15
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/abapgit-xml-only.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: abapGit XML Metadata — XML-Only Objects
-nav_order: 10
+nav_order: 14
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/abapgit.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: abapGit XML Metadata
-nav_order: 9
+nav_order: 13
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/abaplint-local.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: abaplint Local Rules
-nav_order: 21
+nav_order: 17
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/abaplint.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: abaplint Rule Guidelines
-nav_order: 20
+nav_order: 16
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/branch-workflow.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Branch Workflow
-nav_order: 17
+nav_order: 20
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/cds-testing.md

@@ -1,28 +1,250 @@
 ---
 layout: default
 title: CDS Testing
-nav_order: 22
+nav_order: 10
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---
 
 # CDS Testing
 
-### Use CDS Test Double Framework for CDS View Tests
+**Searchable keywords**: CDS test double, CL_CDS_TEST_ENVIRONMENT, IF_CDS_TEST_ENVIRONMENT, insert_test_data, clear_doubles, create_for_multiple_cds, class_setup, class_teardown, aggregation test, CDS unit test
 
-**When creating unit tests for CDS views, use the CDS Test Double Framework (`CL_CDS_TEST_ENVIRONMENT`).**
+## TOPICS IN THIS FILE
+1. When to Use CDS Test Doubles - line 22
+2. Basic Setup Pattern - line 30
+3. Testing CDS Views with Aggregations - line 100
+4. Testing CDS Views that Select from Another CDS View - line 130
+5. Key Classes and Methods - line 170
+6. Important Usage Notes - line 190
+
+---
+
+## 1. When to Use CDS Test Doubles
 
 ```
 ❌ WRONG: Use regular AUnit test class without test doubles
 ✅ CORRECT: Use CL_CDS_TEST_ENVIRONMENT to create test doubles for CDS views
 ```
 
-**Why**: CDS views read from database tables. Using test doubles allows:
-- Injecting test data without affecting production data
-- Testing specific scenarios that may not exist in production
-- Fast, isolated tests that don't depend on database state
+Use the CDS Test Double Framework (`CL_CDS_TEST_ENVIRONMENT`) whenever:
+- A class under test calls `SELECT FROM <cds_view>` directly or via a helper
+- You need controlled test data (not production data)
+- You need to test CDS view logic with specific scenarios
+
+**Why**: CDS views read from database tables. Using test doubles allows injecting test data
+without affecting production data, and keeps tests fast and isolated.
+
+---
+
+## 2. Basic Setup Pattern
+
+The test class lives in `<classname>.clas.testclasses.abap`. The CDS view itself has no
+`.testclasses` file — test it through a regular ABAP class that reads it.
+
+```abap
+"-------------------------
+" CLASS DEFINITION
+"-------------------------
+CLASS ltcl_cds_test DEFINITION FOR TESTING RISK LEVEL HARMLESS DURATION SHORT FINAL.
+
+  PRIVATE SECTION.
+    " IMPORTANT: Use interface type, not class type!
+    DATA mo_cds_env TYPE REF TO if_cds_test_environment.
+
+    " IMPORTANT: class_setup/teardown must be CLASS-METHODS (static)!
+    CLASS-DATA mo_cds_env_static TYPE REF TO if_cds_test_environment.
+
+    METHODS setup.
+    METHODS test_cds_with_doubles FOR TESTING.
+
+    CLASS-METHODS: class_setup,
+                   class_teardown.
+
+ENDCLASS.
+
+"-------------------------
+" CLASS IMPLEMENTATION
+"-------------------------
+CLASS ltcl_cds_test IMPLEMENTATION.
+
+  METHOD class_setup.
+    " Create CDS test environment — framework auto-creates doubles for dependencies
+    mo_cds_env_static = cl_cds_test_environment=>create(
+      i_for_entity = 'ZC_MY_CDS_VIEW' ).
+  ENDMETHOD.
+
+  METHOD class_teardown.
+    " Clean up test environment
+    mo_cds_env_static->destroy( ).
+  ENDMETHOD.
+
+  METHOD setup.
+    " IMPORTANT: Assign static env to instance and clear doubles before each test
+    mo_cds_env = mo_cds_env_static.
+    mo_cds_env->clear_doubles( ).
+  ENDMETHOD.
+
+  METHOD test_cds_with_doubles.
+    " IMPORTANT: Must declare table type first — cannot inline in VALUE #()!
+    DATA lt_test_data TYPE TABLE OF zc_my_cds_view WITH EMPTY KEY.
+    lt_test_data = VALUE #(
+      ( field1 = 'A' field2 = 100 )
+      ( field1 = 'B' field2 = 200 ) ).
+
+    " Insert test data using named parameter
+    mo_cds_env->insert_test_data( i_data = lt_test_data ).
+
+    " Select from CDS view
+    SELECT * FROM zc_my_cds_view INTO TABLE @DATA(lt_result).
+
+    " Verify results
+    cl_abap_unit_assert=>assert_not_initial(
+      act = lt_result
+      msg = 'Result should not be empty' ).
+
+    cl_abap_unit_assert=>assert_equals(
+      act = lines( lt_result )
+      exp = 2
+      msg = 'Expected 2 rows' ).
+  ENDMETHOD.
+
+ENDCLASS.
+```
+
+---
+
+## 3. Testing CDS Views with Aggregations (SUM, COUNT, GROUP BY)
+
+For CDS views with aggregations, insert test data into the **base tables** (SFLIGHT, SCARR,
+SBOOK, etc.), not directly into the CDS view. The framework routes the inserts through the
+aggregation pipeline.
+
+```abap
+METHOD test_aggregation.
+  " Insert data into base tables via CDS test doubles
+  DATA lt_scarr TYPE TABLE OF scarr WITH EMPTY KEY.
+  lt_scarr = VALUE #( ( carrid = 'LH' carrname = 'Lufthansa' currcode = 'EUR' ) ).
+  mo_cds_env->insert_test_data( i_data = lt_scarr ).
+
+  DATA lt_sflight TYPE TABLE OF sflight WITH EMPTY KEY.
+  lt_sflight = VALUE #( ( carrid = 'LH' connid = '0400' fldate = '20240115'
+                          seatsmax = 200 seatsocc = 100 ) ).
+  mo_cds_env->insert_test_data( i_data = lt_sflight ).
+
+  DATA lt_sbook TYPE TABLE OF sbook WITH EMPTY KEY.
+  lt_sbook = VALUE #(
+    ( carrid = 'LH' connid = '0400' fldate = '20240115' bookid = '0001' forcuram = 1000 )
+    ( carrid = 'LH' connid = '0400' fldate = '20240115' bookid = '0002' forcuram = 2000 )
+    ( carrid = 'LH' connid = '0400' fldate = '20240115' bookid = '0003' forcuram = 3000 ) ).
+  mo_cds_env->insert_test_data( i_data = lt_sbook ).
+
+  " Select from CDS view — aggregations will use test double data
+  SELECT * FROM zc_flight_revenue INTO TABLE @DATA(lt_result).
+
+  cl_abap_unit_assert=>assert_equals(
+    exp = 3
+    act = lt_result[ 1 ]-numberofbookings
+    msg = 'Should have 3 bookings' ).
+
+  cl_abap_unit_assert=>assert_equals(
+    exp = '6000.00'
+    act = lt_result[ 1 ]-totalrevenue
+    msg = 'Total revenue should be 6000.00' ).
+ENDMETHOD.
+```
+
+---
+
+## 4. Testing CDS Views that Select from Another CDS View
+
+> **Note:** This pattern applies when your design **already has** a CDS view that selects from
+> another CDS view. It does NOT mean you should split a single view into two — use a single
+> CDS view with GROUP BY / JOIN when the business logic fits.
+
+When your CDS view selects from **another CDS view** (not a base table), `create` raises
+`CX_CDS_FAILURE`. Use `create_for_multiple_cds` instead and list all CDS entities in the
+dependency chain.
+
+```abap
+METHOD class_setup.
+  " ZC_TopView selects from ZC_IntermediateView (another CDS view entity)
+  " → must use create_for_multiple_cds and list all CDS entities
+  mo_cds_env_static = cl_cds_test_environment=>create_for_multiple_cds(
+    i_for_entities = VALUE #(
+      ( 'ZC_TOPVIEW' )           " the view under test
+      ( 'ZC_INTERMEDIATEVIEW' )  " the CDS view it selects from
+    ) ).
+ENDMETHOD.
+```
+
+Insert test data into the **intermediate CDS view** (not the base tables), because that is
+what the top-level view reads:
+
+```abap
+METHOD test_read.
+  DATA lt_source TYPE TABLE OF zc_intermediateview WITH EMPTY KEY.
+  lt_source = VALUE #(
+    ( field1 = 'A' field2 = 100 )
+    ( field1 = 'B' field2 = 200 ) ).
+  mo_cds_env->insert_test_data( i_data = lt_source ).
+
+  SELECT * FROM zc_topview INTO TABLE @DATA(lt_result).
+
+  cl_abap_unit_assert=>assert_equals(
+    exp = 2  act = lines( lt_result )  msg = 'Expected 2 rows' ).
+ENDMETHOD.
+```
+
+**Rules:**
+- List the view under test **and all CDS views it depends on** in `i_for_entities`
+- Insert data into the **direct source** of the top-level view (the intermediate CDS view)
+- Order in `i_for_entities` does not matter
+- If `create` raises `CX_CDS_FAILURE`, switch to `create_for_multiple_cds`
+
+---
+
+## 5. Key Classes and Methods
+
+| Item | Type / Usage |
+|------|-------------|
+| `CL_CDS_TEST_ENVIRONMENT` | Class — entry point, use its `CREATE` / `CREATE_FOR_MULTIPLE_CDS` methods |
+| `IF_CDS_TEST_ENVIRONMENT` | Interface — declare your variable with this type |
+| `CLASS-METHODS class_setup` | Must be static (`CLASS-METHODS`, not `METHODS`) |
+| `CL_ABAP_UNIT_ASSERT` | Standard AUnit assertion class |
+
+| Method | Purpose |
+|--------|---------|
+| `CL_CDS_TEST_ENVIRONMENT=>create( i_for_entity = ... )` | Environment for a CDS view over base tables |
+| `CL_CDS_TEST_ENVIRONMENT=>create_for_multiple_cds( i_for_entities = ... )` | Environment when CDS view selects from another CDS view |
+| `insert_test_data( i_data = ... )` | Inject test rows into a test double |
+| `clear_doubles( )` | Remove all test rows — call in `setup` before each test |
+| `destroy( )` | Tear down the environment — call in `class_teardown` |
+
+---
+
+## 6. Important Usage Notes
+
+1. **Declare with interface type**: `DATA mo_cds_env TYPE REF TO if_cds_test_environment` —
+   `create` returns an interface reference, not a class reference.
+
+2. **Static lifecycle methods**: `class_setup` and `class_teardown` must be `CLASS-METHODS`
+   (not `METHODS`). The environment is expensive to create — build it once per class run.
+
+3. **Table type before VALUE #()**: Must declare `DATA lt_tab TYPE TABLE OF <type> WITH EMPTY KEY`
+   before using `VALUE #()` — inline declaration inside `VALUE #()` is not supported here.
+
+4. **Auto-created dependencies**: When the CDS view selects only from base tables, the framework
+   auto-creates test doubles — do not specify an `i_dependency_list`. When the CDS view selects
+   from another CDS view, use `create_for_multiple_cds` (see section 4).
+
+5. **Aggregations**: For CDS views with SUM/COUNT/GROUP BY, insert test data into the base tables
+   (SFLIGHT, SCARR, etc.), not the CDS view itself.
+
+6. **Clear doubles**: Always call `clear_doubles` in `setup` to ensure test isolation.
+
+7. **Enable associations**: Set `test_associations = 'X'` in `create` only when explicitly
+   testing CDS association navigation.
 
-See `abapgit-agent ref --topic testing` for full code examples including:
-- Basic CDS test double setup
-- Testing CDS views with aggregations (insert into base tables)
-- Testing CDS views that select from another CDS view (`create_for_multiple_cds`)
+8. **Exception handling**: Declare test methods with `RAISING cx_static_check` if the code
+   under test raises checked exceptions.

package/abap/guidelines/cds.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: CDS Views
-nav_order: 5
+nav_order: 9
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/classes.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Classes & Objects
-nav_order: 6
+nav_order: 4
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/comments.md

@@ -0,0 +1,249 @@
+---
+layout: default
+title: Documentation Comments
+nav_order: 6
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
+# ABAP Documentation Comments
+
+**Searchable keywords**: ABAP DOC, "! comment, shorttext synchronized, @parameter, @raising, inline comment, CDS comment, // comment, program header, *&---, documentation comment
+
+## TOPICS IN THIS FILE
+1. Two Types of Comments - line 18
+2. OO Class Documentation (CLAS) - line 37
+3. Interface Documentation (INTF) - line 101
+4. Program Header (PROG) - line 120
+5. CDS View Comments (DDLS) - line 137
+6. When NOT to Comment - line 161
+7. Quick Decision Table - line 182
+
+---
+
+## 1. Two Types of Comments
+
+ABAP has two distinct comment styles with different purposes:
+
+**`"!` (ABAP DOC)** — parsed by the ABAP system; surfaced in ADT and SE24 as F2 help.
+Use for API-level documentation: class declarations, interface declarations, and method signatures.
+This is the equivalent of Javadoc. The system reads it — it is metadata, not decoration.
+
+**`"!` is only valid immediately before these statements:**
+`CLASS ... DEFINITION`, `INTERFACE`, `METHODS`, `CLASS-METHODS`, `EVENTS`, `DATA`, `CLASS-DATA`, `CONSTANTS`.
+
+**`"!` before `TYPES` is a syntax error** — the Code Inspector reports "ABAP Doc comment is in the wrong position."
+Use a regular `"` comment to describe type structures instead.
+
+**`"` (regular inline comment)** — source-only; not parsed by the ABAP system.
+Use inside method bodies to explain non-obvious logic, and to label `TYPES` blocks.
+Never use `"!` inside method implementations — it has no effect there.
+
+**Default behaviour (when to add automatically vs. only on request):**
+
+| Comment Type | Default Behaviour |
+|---|---|
+| `"! <p class="shorttext synchronized">` on CLASS/INTF | **Always auto-add** — synced to XML `<DESCRIPT>`; it IS object metadata |
+| `@EndUserText.label` on CDS view | **Always auto-add** — same: it IS the CDS description |
+| `"!` + `@parameter` on INTF public methods | **Always auto-add** — interfaces are the contract; self-documenting |
+| `"!` + `@parameter` on CLAS public methods | **Auto-add** when creating a new class from scratch |
+| `"!` on existing CLAS private/protected methods | **Only if requested** — adding to existing code is refactoring |
+| `"` inline comments inside method bodies | **Only when non-obvious** — never add redundant comments |
+| `*&---` program header | **Always auto-add** — standard for every PROG |
+
+---
+
+## 2. OO Class Documentation (CLAS)
+
+### Class-level shorttext
+
+Place the `"!` shorttext immediately before `CLASS ... DEFINITION`:
+
+```abap
+"! <p class="shorttext synchronized">Pull ABAP objects from a remote git repository</p>
+CLASS zcl_abgagt_agent DEFINITION PUBLIC FINAL CREATE PUBLIC.
+```
+
+This shorttext is **synced to the XML `<DESCRIPT>` field** by abapGit. Creating a class without
+it means the XML description is blank and the object cannot be searched by description in SE24/SE80.
+**Always add it** when creating any new class.
+
+**Note on `*"*` auto-header:** When a class has local definitions or inherits from another class,
+abapGit writes a 3-line `*"*"` block at the top of the `.clas.abap` file:
+
+```abap
+*"* use this source file for the definition and implementation of
+*"* local helper classes, interface definitions and type
+*"* temporary on-the-fly implementation
+```
+
+In that case, the `"!` shorttext goes on line 4 (after the block), not line 1.
+
+### Method documentation
+
+Place `"!` documentation in the DEFINITION section, PUBLIC SECTION only, immediately before the
+`METHODS` statement:
+
+```abap
+"! Pull files from remote and activate them
+"! @parameter it_files | List of files to activate (relative paths)
+"! @parameter rv_success | True if all objects activated successfully
+"! @raising zcx_abapgit_exception | If pull or activation fails
+METHODS pull_files
+  IMPORTING it_files          TYPE string_table
+  RETURNING VALUE(rv_success) TYPE abap_bool
+  RAISING   zcx_abapgit_exception.
+```
+
+**Rules:**
+
+- **ALWAYS add** `"! <p class="shorttext synchronized">` when creating any new CLASS — no exceptions.
+- **ALWAYS add** `"!` + `@parameter` for all PUBLIC methods when creating a new class from scratch.
+- When **modifying existing** code, only add or update comments if explicitly asked.
+- `@parameter <name> | <description>` — one line per IMPORTING/EXPORTING/RETURNING/CHANGING param.
+- `@raising <exception> | <reason>` — one line per RAISING exception.
+- PRIVATE and PROTECTED methods: optional; add only if the purpose is non-obvious.
+- Place ONLY in the DEFINITION section — do NOT repeat `"!` in the IMPLEMENTATION section.
+
+**Full example:**
+
+```abap
+"! <p class="shorttext synchronized">Syntax checker for ABAP class source</p>
+CLASS zcl_abgagt_syntax_chk_clas DEFINITION PUBLIC FINAL CREATE PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES zif_abgagt_syntax_checker.
+
+    "! Create a new syntax checker instance
+    "! @parameter ii_agent | Agent used for HTTP communication
+    CLASS-METHODS create
+      IMPORTING ii_agent        TYPE REF TO zif_abgagt_agent
+      RETURNING VALUE(ro_check) TYPE REF TO zif_abgagt_syntax_checker.
+
+  PRIVATE SECTION.
+    DATA mi_agent TYPE REF TO zif_abgagt_agent.
+ENDCLASS.
+```
+
+---
+
+## 3. Interface Documentation (INTF)
+
+Interfaces follow the same `"!` pattern as classes. The shorttext goes immediately before
+`INTERFACE ... PUBLIC`, and every method gets `"!` + `@parameter`.
+
+```abap
+"! <p class="shorttext synchronized">Contract for all syntax checker implementations</p>
+INTERFACE zif_abgagt_syntax_checker PUBLIC.
+
+  "! Check the syntax of ABAP source code
+  "! @parameter iv_source | Full ABAP source text to check
+  "! @parameter rv_result | JSON-encoded result with errors list
+  "! @raising zcx_abapgit_exception | On communication failure
+  METHODS check_syntax
+    IMPORTING iv_source        TYPE string
+    RETURNING VALUE(rv_result) TYPE string
+    RAISING   zcx_abapgit_exception.
+
+ENDINTERFACE.
+```
+
+**Canonical example:** `zif_abgagt_syntax_checker.intf.abap` in this repository.
+
+**Rules:**
+- **ALWAYS add** `"! <p class="shorttext synchronized">` for every new interface.
+- **ALWAYS add** `"!` + `@parameter` for every method — interfaces are the published contract.
+- No exceptions for "obvious" method names — document them anyway.
+
+---
+
+## 4. Program Header (PROG)
+
+Programs use the traditional `*&---` block, NOT ABAP DOC. Place it before the `REPORT` statement:
+
+```abap
+*&---------------------------------------------------------------------*
+*& Report Z_MY_PROGRAM
+*&---------------------------------------------------------------------*
+*& Brief description of what the program does
+*&---------------------------------------------------------------------*
+REPORT z_my_program.
+```
+
+**Rules:**
+- **ALWAYS add** this header block when creating any new program.
+- Do NOT add `"! <p class="shorttext synchronized">` before `REPORT` — it is not parsed there.
+- Inline comments inside `START-OF-SELECTION` and other events use the regular `"` style.
+
+---
+
+## 5. CDS View Comments (DDLS)
+
+CDS DDL source (`.ddls.asddls`) uses a completely different comment syntax from ABAP:
+
+- Line comment: `// text`
+- Block comment: `/* text */`
+
+**Never use ABAP-style `"` inside CDS source** — it causes a CDS syntax error.
+
+### `@EndUserText.label` — the CDS equivalent of shorttext
+
+This annotation IS the object description. Always include it before the view entity definition:
+
+```cds
+@EndUserText.label: 'Revenue summary by carrier'
+define view entity ZC_FlightRevenue
+  as select from sflight
+{
+  key carrid,         // IATA carrier code
+  key connid,         // Connection number
+  sum( price ) as TotalRevenue
+}
+```
+
+**Rules:**
+- **ALWAYS add** `@EndUserText.label` when creating any new CDS view entity.
+- Add `// text` line comments after non-obvious field names.
+- Use `/* ... */` for multi-line block comments if needed (e.g., explaining a complex join).
+- No `"!` or `"` comments anywhere in `.ddls.asddls` files.
+
+---
+
+## 6. When NOT to Comment
+
+The guiding principle: **comments explain *why*, not *what***.
+
+```abap
+" BAD — repeats the code, adds no value
+ls_params-mode = 'abort'.   " Set mode to abort
+
+" GOOD — explains a non-obvious rule
+ls_params-mode = 'abort'.   " INITIAL means abort (caller omitting the field = abort semantics)
+```
+
+**Do NOT add comments when:**
+- The comment would just restate the variable name or method call.
+- A private helper method simply delegates to an interface method (the name is self-explanatory).
+- `@parameter` description would be identical to the parameter name (e.g., `"! @parameter iv_name | Name`).
+- You are modifying existing code and the task did not ask for documentation changes.
+
+**DO add comments when:**
+- The logic involves a non-obvious ABAP-specific behaviour or workaround.
+- There is a caller precondition that cannot be expressed in the method signature.
+- A COND/SWITCH mapping table needs to explain the business rule behind each branch.
+- A loop exit or CONTINUE has a non-obvious condition.
+
+---
+
+## 7. Quick Decision Table
+
+| Object | Where | Style | Required? |
+|--------|-------|-------|-----------|
+| CLAS (global) | Before `CLASS DEFINITION` | `"! <p class="shorttext synchronized">` | **Always** |
+| CLAS public method | Before `METHODS` in DEFINITION | `"! desc` + `"! @parameter` | Yes (new objects) |
+| CLAS private/protected method | Before `METHODS` in DEFINITION | `"! desc` | Only if non-obvious |
+| INTF method | Before `METHODS` in interface | `"! desc` + `"! @parameter` | **Always** |
+| PROG | First lines before `REPORT` | `*&---` block | **Always** |
+| DDLS view entity | Before `define view entity` | `@EndUserText.label` annotation | **Always** |
+| DDLS field | After field name | `// text` | For non-obvious fields |
+| Method body | Inside `METHOD...ENDMETHOD` | `" text` | Only for non-obvious logic |
+| TYPES block | Before `TYPES:` in interface/class | `" text` | Optional — `"!` is invalid here |

package/abap/guidelines/common-errors.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Common ABAP Errors
-nav_order: 14
+nav_order: 12
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/debug-dump.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Dump Analysis Guide
-nav_order: 16
+nav_order: 19
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/debug-session.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Debug Session Guide
-nav_order: 15
+nav_order: 18
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/index.md

@@ -31,6 +31,7 @@ This folder contains detailed ABAP coding guidelines that can be searched using
 | `object-creation.md` | Object Creation (XML metadata, local classes) |
 | `cds-testing.md` | CDS Testing (Test Double Framework) |
 | `abaplint.md` | abaplint Rule Guidelines (prefer_inline trap, safe patterns) |
+| `comments.md` | Documentation Comments (ABAP DOC, shorttext, @parameter, CDS //) |
 
 ## Usage
 

package/abap/guidelines/json.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: JSON Handling
-nav_order: 8
+nav_order: 11
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/object-creation.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Object Creation
-nav_order: 19
+nav_order: 22
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---
@@ -17,26 +17,29 @@ Replace `<name>` with the actual object name from this project's naming conventi
 
 | Object Type | ABAP Source File | XML File | Details |
 |-------------|-----------------|----------|---------|
-| Class | `<name>.clas.abap` | `<name>.clas.xml` | See `guidelines/abapgit.md` |
-| Interface | `<name>.intf.abap` | `<name>.intf.xml` | See `guidelines/abapgit.md` |
-| Program | `<name>.prog.abap` | `<name>.prog.xml` | See `guidelines/abapgit.md` |
-| **CDS View Entity** | `<name>.ddls.asddls` | `<name>.ddls.xml` | **Use by default** - See `guidelines/cds.md` |
-| CDS View (legacy) | `<name>.ddls.asddls` | `<name>.ddls.xml` | Only if explicitly requested - See `guidelines/cds.md` |
-| Table (TABL) | *(none — XML-only)* | `<name>.tabl.xml` | See `guidelines/abapgit.md` |
-| Structure (STRU) | *(none — XML-only)* | `<name>.stru.xml` | See `guidelines/abapgit.md` |
-| Data Element (DTEL) | *(none — XML-only)* | `<name>.dtel.xml` | See `guidelines/abapgit.md` |
-| Table Type (TTYP) | *(none — XML-only)* | `<name>.ttyp.xml` | See `guidelines/abapgit.md` |
-
-> **XML-only objects (TABL, STRU, DTEL, TTYP)**: create only the `.xml` file — there is no `.abap` source file.
+| Class (CLAS) | `<name>.clas.abap` | `<name>.clas.xml` | `ref --topic abapgit` |
+| Interface (INTF) | `<name>.intf.abap` | `<name>.intf.xml` | `ref --topic abapgit` |
+| Program (PROG) | `<name>.prog.abap` | `<name>.prog.xml` | `ref --topic abapgit` |
+| CDS View Entity (DDLS) | `<name>.ddls.asddls` | `<name>.ddls.xml` | **Use by default** — `ref --topic abapgit` |
+| CDS Access Control (DCLS) | `<name>.dcls.asdcls` | `<name>.dcls.xml` | `ref --topic abapgit` |
+| Function Group (FUGR) | `<name>.fugr.abap` + includes | `<name>.fugr.xml` | `ref --topic abapgit` |
+| Table (TABL) | *(none — XML-only)* | `<name>.tabl.xml` | `ref --topic abapgit-xml-only` |
+| Structure (STRU) | *(none — XML-only)* | `<name>.stru.xml` | `ref --topic abapgit-xml-only` |
+| Data Element (DTEL) | *(none — XML-only)* | `<name>.dtel.xml` | `ref --topic abapgit-xml-only` |
+| Table Type (TTYP) | *(none — XML-only)* | `<name>.ttyp.xml` | `ref --topic abapgit-xml-only` |
+| Domain (DOMA) | *(none — XML-only)* | `<name>.doma.xml` | `ref --topic abapgit-xml-only` |
+| Message Class (MSAG) | *(none — XML-only)* | `<name>.msag.xml` | `ref --topic abapgit-xml-only` |
+
+> **XML-only objects (TABL, STRU, DTEL, TTYP, DOMA, MSAG)**: create only the `.xml` file — there is no `.abap` source file.
 > After committing and pushing, pull with: `pull --files <folder>/<name>.tabl.xml --sync-xml`
 
-**IMPORTANT: When user says "create CDS view", create CDS View Entity by default.**
+**IMPORTANT: When user says "create CDS view", create CDS View Entity (DDLS) by default.**
 
 **Why:** Modern S/4HANA standard, simpler (no SQL view), no namespace conflicts.
 
 **For complete XML templates, DDL examples, and detailed comparison:**
-- **CDS Views**: `guidelines/cds.md`
-- **XML templates**: `guidelines/abapgit.md`
+- **CDS Views + DCLS + FUGR**: `abapgit-agent ref --topic abapgit`
+- **XML-only objects**: `abapgit-agent ref --topic abapgit-xml-only`
 
 ---
 

package/abap/guidelines/objects.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Naming Conventions
-nav_order: 7
+nav_order: 5
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/testing.md

@@ -1,14 +1,14 @@
 ---
 layout: default
 title: Unit Testing
-nav_order: 4
+nav_order: 7
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---
 
 # Unit Testing
 
-**Searchable keywords**: unit test, AUnit, test class, cl_abap_unit_assert, FOR TESTING, setup, teardown, RISK LEVEL, DURATION, CDS test double, CL_CDS_TEST_ENVIRONMENT
+**Searchable keywords**: unit test, AUnit, test class, cl_abap_unit_assert, FOR TESTING, setup, teardown, RISK LEVEL, DURATION, WITH_UNIT_TESTS, testclasses
 
 ## TOPICS IN THIS FILE
 1. Local Test Classes - line 22
@@ -16,8 +16,6 @@ grand_parent: ABAP Development
 3. Required Elements - line 35
 4. Naming Conventions - line 67
 5. Common Mistake: DDLS Testing - line 133
-6. CDS Test Doubles - line 163
-7. CDS with Aggregations - line 247
 
 ## Unit Testing with Local Test Classes
 
@@ -169,206 +167,10 @@ Or via abapGit: Pull the files and run tests in the ABAP system.
 
 ## Unit Testing CDS Views
 
-When testing code that uses CDS view entities, you can use the **CDS Test Double Framework** (`CL_CDS_TEST_ENVIRONMENT`) to create test doubles for CDS views. This allows you to inject test data without affecting production data.
-
-### When to Use CDS Test Doubles
-
-- Testing code that reads from CDS views
-- Need controlled test data (not production data)
-- Testing CDS view logic with specific scenarios
-
-### CDS Test Double Framework
-
-Use `CL_CDS_TEST_ENVIRONMENT` for controlled test data:
-
-```abap
-"-------------------------
-" CLASS DEFINITION
-"-------------------------
-CLASS ltcl_cds_test DEFINITION FOR TESTING RISK LEVEL HARMLESS DURATION SHORT FINAL.
-
-  PRIVATE SECTION.
-    " IMPORTANT: Use interface type, not class type!
-    DATA mo_cds_env TYPE REF TO if_cds_test_environment.
-
-    " IMPORTANT: class_setup/teardown must be CLASS-METHODS (static)!
-    CLASS-DATA mo_cds_env_static TYPE REF TO if_cds_test_environment.
-
-    METHODS setup.
-    METHODS test_cds_with_doubles FOR TESTING.
-
-    CLASS-METHODS: class_setup,
-                   class_teardown.
-
-ENDCLASS.
-
-"-------------------------
-" CLASS IMPLEMENTATION
-"-------------------------
-CLASS ltcl_cds_test IMPLEMENTATION.
-
-  METHOD class_setup.
-    " Create CDS test environment - framework auto-creates doubles for dependencies
-    mo_cds_env_static = cl_cds_test_environment=>create(
-      i_for_entity = 'ZC_MY_CDS_VIEW' ).
-  ENDMETHOD.
-
-  METHOD class_teardown.
-    " Clean up test environment
-    mo_cds_env_static->destroy( ).
-  ENDMETHOD.
-
-  METHOD setup.
-    " IMPORTANT: Assign static env to instance and clear doubles
-    mo_cds_env = mo_cds_env_static.
-    mo_cds_env->clear_doubles( ).
-  ENDMETHOD.
-
-  METHOD test_cds_with_doubles.
-    " IMPORTANT: Must declare table type first, cannot inline in VALUE!
-    DATA lt_test_data TYPE TABLE OF zc_my_cds_view WITH EMPTY KEY.
-    lt_test_data = VALUE #(
-      ( field1 = 'A' field2 = 100 )
-      ( field1 = 'B' field2 = 200 ) ).
-
-    " Insert test data using named parameter
-    mo_cds_env->insert_test_data( i_data = lt_test_data ).
-
-    " Select from CDS view
-    SELECT * FROM zc_my_cds_view INTO TABLE @DATA(lt_result).
-
-    " Verify results
-    cl_abap_unit_assert=>assert_not_initial(
-      act = lt_result
-      msg = 'Result should not be empty' ).
-
-    cl_abap_unit_assert=>assert_equals(
-      act = lines( lt_result )
-      exp = 2
-      msg = 'Expected 2 rows' ).
-  ENDMETHOD.
-
-ENDCLASS.
-```
-
-### Testing CDS Views with Aggregations (SUM, COUNT, GROUP BY)
-
-For CDS views with aggregations, insert test data into the **base tables** (SFLIGHT, SCARR, SBOOK), not directly into the CDS view:
-
-```abap
-METHOD test_aggregation.
-  " Insert data into base tables via CDS test doubles
-  DATA lt_scarr TYPE TABLE OF scarr WITH EMPTY KEY.
-  lt_scarr = VALUE #( ( carrid = 'LH' carrname = 'Lufthansa' currcode = 'EUR' ) ).
-  mo_cds_env->insert_test_data( i_data = lt_scarr ).
-
-  DATA lt_sflight TYPE TABLE OF sflight WITH EMPTY KEY.
-  lt_sflight = VALUE #( ( carrid = 'LH' connid = '0400' fldate = '20240115'
-                          seatsmax = 200 seatsocc = 100 ) ).
-  mo_cds_env->insert_test_data( i_data = lt_sflight ).
-
-  DATA lt_sbook TYPE TABLE OF sbook WITH EMPTY KEY.
-  lt_sbook = VALUE #(
-    ( carrid = 'LH' connid = '0400' fldate = '20240115' bookid = '0001' forcuram = 1000 )
-    ( carrid = 'LH' connid = '0400' fldate = '20240115' bookid = '0002' forcuram = 2000 )
-    ( carrid = 'LH' connid = '0400' fldate = '20240115' bookid = '0003' forcuram = 3000 ) ).
-  mo_cds_env->insert_test_data( i_data = lt_sbook ).
-
-  " Select from CDS view - aggregations will use test double data
-  SELECT * FROM zc_flight_revenue INTO TABLE @DATA(lt_result).
-
-  " Verify aggregations
-  cl_abap_unit_assert=>assert_equals(
-    exp = 3
-    act = lt_result[ 1 ]-numberofbookings
-    msg = 'Should have 3 bookings' ).
-
-  cl_abap_unit_assert=>assert_equals(
-    exp = '6000.00'
-    act = lt_result[ 1 ]-totalrevenue
-    msg = 'Total revenue should be 6000.00' ).
-ENDMETHOD.
-```
-
-### Testing CDS Views that Select from Another CDS View
-
-> **Note:** This pattern applies when your design **already has** a CDS view that selects from another CDS view. It does NOT mean you should split a single view into two — use a single CDS view with GROUP BY / JOIN when the business logic fits.
-
-When your CDS view selects from **another CDS view** (not a base table), `create` will raise `CX_CDS_FAILURE`. Use `create_for_multiple_cds` instead and list all CDS entities in the dependency chain.
-
-```abap
-METHOD class_setup.
-  " ZC_TopView selects from ZC_IntermediateView (another CDS view entity)
-  " → must use create_for_multiple_cds and list all CDS entities
-  mo_cds_env_static = cl_cds_test_environment=>create_for_multiple_cds(
-    i_for_entities = VALUE #(
-      ( 'ZC_TOPVIEW' )           " the view under test
-      ( 'ZC_INTERMEDIATEVIEW' )  " the CDS view it selects from
-    ) ).
-ENDMETHOD.
-```
-
-Insert test data into the intermediate CDS view (not the base tables), since that is what the top-level view reads:
-
-```abap
-METHOD test_read.
-  DATA lt_source TYPE TABLE OF zc_intermediateview WITH EMPTY KEY.
-  lt_source = VALUE #(
-    ( field1 = 'A' field2 = 100 )
-    ( field1 = 'B' field2 = 200 ) ).
-  mo_cds_env->insert_test_data( i_data = lt_source ).
-
-  SELECT * FROM zc_topview INTO TABLE @DATA(lt_result).
-
-  cl_abap_unit_assert=>assert_equals(
-    exp = 2  act = lines( lt_result )  msg = 'Expected 2 rows' ).
-ENDMETHOD.
-```
-
-**Rules:**
-- List the view under test **and all CDS views it depends on** in `i_for_entities`
-- Insert data into the **direct source** of the top-level view (the intermediate CDS view)
-- Order in `i_for_entities` does not matter
-- If you get `CX_CDS_FAILURE` when using `create`, switch to `create_for_multiple_cds`
-
----
-
-### Key Classes for CDS Testing
-
-| Item | Type/Usage |
-|------|------------|
-| `CL_CDS_TEST_ENVIRONMENT` | Class with `CREATE` method |
-| `IF_CDS_TEST_ENVIRONMENT` | Interface (CREATE returns this type) |
-| `CLASS-METHODS` | `class_setup` and `class_teardown` must be static methods |
-| `CL_OSQL_TEST_ENVIRONMENT` | Test doubles for database tables (use for aggregations) |
-| `CL_ABAP_UNIT_ASSERT` | Assertions |
-
-### Key Methods
-
-| Method | Purpose |
-|--------|---------|
-| `CL_CDS_TEST_ENVIRONMENT=>create( i_for_entity = ... )` | Create test environment for a CDS view over base tables |
-| `CL_CDS_TEST_ENVIRONMENT=>create_for_multiple_cds( i_for_entities = ... )` | Create test environment when the CDS view selects from another CDS view |
-| `insert_test_data( i_data = ... )` | Insert test data into test doubles |
-| `clear_doubles` | Clear test data before each test method |
-| `destroy` | Clean up after test class |
-
-### Important Usage Notes
-
-1. **Use interface type**: `DATA mo_cds_env TYPE REF TO if_cds_test_environment` - the CREATE method returns an interface reference
-2. **CLASS-METHODS required**: `class_setup` and `class_teardown` must be declared with `CLASS-METHODS` (not `METHODS`)
-3. **Table type declaration**: Must declare `DATA lt_tab TYPE TABLE OF <type> WITH EMPTY KEY` before using `VALUE #()`
-4. **Auto-created dependencies**: When the CDS view selects only from **base tables**, the framework auto-creates test doubles — do not specify `i_dependency_list`. When the CDS view selects from **another CDS view**, use `create_for_multiple_cds` instead (see section below).
-5. **Aggregations**: For CDS views with SUM/COUNT/GROUP BY, insert test data into base tables (SFLIGHT, SCARR, etc.)
-6. **Clear doubles**: Call `clear_doubles` in `setup` method before each test
-7. **Enable associations**: Set `test_associations = 'X'` only if testing CDS associations
-8. **Exception handling**: Declare test methods with `RAISING cx_static_check` for proper exception handling
-
-### Search Reference for More Details
+For full CDS test double patterns (basic setup, aggregations, CDS-on-CDS), see:
 
 ```bash
-abapgit-agent ref "cl_cds_test_environment"
-abapgit-agent ref --topic unit-tests
+abapgit-agent ref --topic cds-testing
 ```
 
 ---

package/abap/guidelines/unit-testable-code.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Unit Testable Code
-nav_order: 13
+nav_order: 8
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/workflow-detailed.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Development Workflow (Detailed)
-nav_order: 18
+nav_order: 21
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "files": [
     "bin/",
@@ -37,6 +37,7 @@
     "test:cmd:tree": "node tests/run-all.js --cmd --command=tree",
     "test:cmd:dump": "node tests/run-all.js --cmd --command=dump",
     "test:cmd:debug": "node tests/run-all.js --cmd --command=debug",
+    "test:debug": "node tests/run-all.js --debug",
     "test:debug:scenarios": "bash tests/integration/debug-scenarios.sh",
     "test:debug:scenarios:1": "bash tests/integration/debug-scenarios.sh 1",
     "test:debug:scenarios:2": "bash tests/integration/debug-scenarios.sh 2",

package/src/commands/debug.js

@@ -109,8 +109,23 @@ function objectUri(name, includeType) {
   }
   // FUGR source includes: L<group>U<NN>, L<group>TOP, L<group>F<NN>, etc.
   // All start with 'L'. Customer Z/Y programs never start with 'L'.
+  // Correct ADT URI (verified against abap-adt-api):
+  //   /sap/bc/adt/functions/groups/<group>/includes/<include>/source/main
+  // NOT /programs/includes/ — that path is for standalone PROG/I includes only.
+  // Group name is derived by stripping leading 'L' and trailing suffix:
+  //   U<NN>  — FM source include (U01, U02, ...)
+  //   TOP    — pool include
+  //   F<NN>  — form include
+  //   XX     — internal include
   if (/^L/.test(upper)) {
-    return `/sap/bc/adt/programs/includes/${lower}`;
+    const withoutL = upper.slice(1); // e.g. ZCAIS_DEMOU01
+    const group = withoutL
+      .replace(/U\d+$/, '')   // strip Unn suffix
+      .replace(/TOP$/, '')    // strip TOP suffix
+      .replace(/F\d+$/, '')   // strip Fnn suffix
+      .replace(/XX$/, '')     // strip XX suffix
+      .toLowerCase();
+    return `/sap/bc/adt/functions/groups/${group}/includes/${lower}/source/main`;
   }
   return `/sap/bc/adt/programs/programs/${lower}`;
 }
@@ -236,15 +251,25 @@ async function refreshBreakpoints(config, adt, bps) {
 
   const serverResults = parseBreakpointResponse(resp.body || '', bps);
 
-  // Match server results back to local bps by uri+line
+  // Match server results back to local bps by uri+line.
+  // ADT may return a different canonical URI than what was sent (e.g. it rewrites
+  // /functions/groups/<g>/includes/<inc>/... to /functions/groups/<g>/fmodules/<fm>/...).
+  // Fall back to matching by line alone when URI doesn't match, then adopt the
+  // server's canonical URI so future refreshes continue to work.
   const valid = [];
   const stale = [];
   for (const bp of bps) {
-    const match = serverResults.find(r => r.uri === bp.uri && r.line === bp.line);
+    let match = serverResults.find(r => r.uri === bp.uri && r.line === bp.line);
+    if (!match) {
+      // Fallback: match by line number alone (handles URI canonicalization by ADT)
+      match = serverResults.find(r => r.line === bp.line);
+    }
     if (match && match.error) {
       stale.push({ ...bp, error: match.error });
     } else if (match && match.id) {
-      valid.push({ ...bp, id: match.id });
+      // Adopt the server's canonical URI so subsequent refreshes match correctly
+      const canonicalUri = match.uri || bp.uri;
+      valid.push({ ...bp, id: match.id, uri: canonicalUri });
     } else {
       // No match in response — server silently dropped it (e.g. expired)
       stale.push({ ...bp, error: 'Not registered on server' });
@@ -398,9 +423,16 @@ async function cmdSet(args, config, adt) {
   }
 
   // Update local state with server-assigned IDs
+  // Use URI+line match first; fall back to line-only for FUGR where ADT rewrites
+  // /includes/<inc>/ to /fmodules/<fm>/ in the response.
   const updatedWithServerIds = updated.map(bp => {
-    const sr = serverResults.find(r => r.uri === bp.uri && r.line === bp.line);
-    return sr && sr.id ? { ...bp, id: sr.id } : bp;
+    const sr = serverResults.find(r => r.uri === bp.uri && r.line === bp.line)
+      || serverResults.find(r => r.line === bp.line);
+    if (sr && sr.id) {
+      const canonicalUri = sr.uri || bp.uri;
+      return { ...bp, id: sr.id, uri: canonicalUri };
+    }
+    return bp;
   });
   if (_saveBpState) _saveBpState(config, updatedWithServerIds);
 
@@ -435,7 +467,8 @@ async function cmdSet(args, config, adt) {
 
   if (jsonOutput) {
     const out = added.map(a => {
-      const sr = serverResults.find(r => r.uri === a.uri && r.line === a.line);
+      const sr = serverResults.find(r => r.uri === a.uri && r.line === a.line)
+        || serverResults.find(r => r.line === a.line);
       return { id: (sr && sr.id) || null, object: a.name, line: a.line };
     });
     console.log(JSON.stringify(out.length === 1 ? out[0] : out));