abapgit-agent 1.15.2 → 1.16.0

package/abap/.github/copilot-instructions.slim.md

@@ -36,8 +36,14 @@ The folder is configured in `.abapGitAgent` (property: `folder`):
 
 Each ABAP object needs an XML metadata file. Local helper/test-double classes use separate `.locals_def.abap` / `.locals_imp.abap` files.
 
+**Name length limits** (verify before naming anything):
+- CLAS, INTF: name **30 chars** | method names: **30 chars**
+- TABL, STRU: name **30 chars** | **field names: 16 chars** ← most common mistake
+- DDLS (CDS view entity): **40 chars** | field alias: 30 | FUGR: 26 | MSAG: 20 | PROG/DTEL/DOMA/TTYP: 30
+
 ```bash
-abapgit-agent ref --topic object-creation   # XML templates and local class setup
+abapgit-agent ref --topic naming-limits    # full length reference
+abapgit-agent ref --topic object-creation  # XML templates and local class setup
 ```
 
 ### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG, DDLS)
@@ -65,6 +71,24 @@ abapgit-agent ref --topic debug-session       # full debug guide
 abapgit-agent ref --topic debug-dump          # dump analysis guide
 ```
 
+### 7. Never Run `run` Command Proactively
+
+Never call `abapgit-agent run` unless the user explicitly asks — it can modify data or trigger RFCs.
+
+### 8. Probe and PoC Objects — Always Z/Y, Never in SAP Packages
+
+When `objects.local.md` shows SAP namespace (`CL_*`, `IF_*`, `/NAMESPACE/*`) and the user asks to create a new object, always ask first: *"Is this a production object, a PoC, or a probe?"*
+
+→ `abapgit-agent ref --topic probe-poc`
+
+### 9. abaplint — Optional, Project-Controlled
+
+Only run if `.abaplint.json` exists. Run after `syntax`, before commit. Always check `ref --topic abaplint` before applying any quickfix.
+
+```bash
+ls .abaplint.json 2>/dev/null && abapgit-agent lint
+```
+
 ---
 
 ## Development Workflow
@@ -77,6 +101,8 @@ Checked into the repository — applies to all developers. **Read this file at t
 |---------|--------|
 | `safeguards.requireFilesForPull: true` | Always include `--files` in every `pull` |
 | `safeguards.disablePull: true` | Do not run `abapgit-agent pull` at all |
+| `safeguards.disableRun: true` | Do not run `abapgit-agent run` at all |
+| `safeguards.disableProbeClasses: true` | Use `scratchWorkspace` for probe classes instead |
 | `conflictDetection.mode: "abort"` | Abort pull on conflict — inform user |
 | `transports.allowCreate/allowRelease: false` | Blocked — inform user |
 
@@ -97,10 +123,15 @@ abapgit-agent ref --topic branch-workflow
 ```
 Modified ABAP files?
 ├─ CLAS/INTF/PROG/DDLS files?
-│  ├─ Independent files?  → syntax → commit → push → pull
-│  └─ Dependent files?    → skip syntax → commit → push → pull
+│  ├─ Independent files?  → syntax → [abaplint] → commit → push → pull --sync-xml
+│  └─ Dependent files?    → skip syntax → [abaplint] → commit → push → pull --sync-xml
 └─ Other types (FUGR, TABL, etc.)?
-   → skip syntax → commit → push → pull → (if errors: inspect)
+   ├─ XML-only (TABL, STRU, DTEL, TTYP, DOMA, MSAG)?
+   │  → skip syntax → [abaplint] → commit → push → pull --files <name>.tabl.xml --sync-xml
+   └─ FUGR and others?
+      → skip syntax → [abaplint] → commit → push → pull --sync-xml → (if errors: inspect)
+
+[abaplint] = run lint only if .abaplint.json exists; ref --topic abaplint before any quickfix
 ```
 
 ```bash

package/abap/CLAUDE.md

@@ -99,6 +99,20 @@ Never assume Z/Y prefix without checking.
            XML-only objects (TABL, STRU, DTEL, TTYP, DOMA, MSAG) need ONLY the XML file
 ```
 
+**Before choosing a name, verify the length limit for the object type:**
+
+| Object type | Name limit | Field/sub-element limit |
+|---|---|---|
+| CLAS, INTF | **30 chars** | method names: **30 chars** |
+| TABL, STRU | **30 chars** | **field names: 16 chars** |
+| DDLS (CDS view entity) | **40 chars** | field alias: **30 chars** |
+| DCLS (CDS access control) | **40 chars** | — (name must match its DDLS view) |
+| FUGR (function group) | **26 chars** | function module name: **30 chars** |
+| MSAG (message class) | **20 chars** | — |
+| PROG, DTEL, DOMA, TTYP | **30 chars** | — |
+
+→ Full length reference: `abapgit-agent ref --topic naming-limits`
+
 Use the object name from `objects.local.md` (or `objects.md` as fallback) in place of `<name>`:
 
 | Object Type | Source File | XML File |
@@ -110,7 +124,7 @@ Use the object name from `objects.local.md` (or `objects.md` as fallback) in pla
 | CDS Access Control (DCLS) | `<name>.dcls.asdcls` | `<name>.dcls.xml` |
 | Function Group (FUGR) | `<name>.fugr.abap` + includes | `<name>.fugr.xml` |
 | Table (TABL) | *(none)* | `<name>.tabl.xml` |
-| Structure (STRU) | *(none)* | `<name>.stru.xml` |
+| Structure (STRU) | *(none)* | `<name>.tabl.xml` ⚠️ NOT `.stru.xml` |
 | Data Element (DTEL) | *(none)* | `<name>.dtel.xml` |
 | Table Type (TTYP) | *(none)* | `<name>.ttyp.xml` |
 | Domain (DOMA) | *(none)* | `<name>.doma.xml` |
@@ -143,7 +157,7 @@ Anything else (SAP namespace object, or SAP-delivered package)?
 
         Object:   <NAME> (<Type>)
         Package:  <PACKAGE>
-        Files:    <folder>/<name>.<ext>.abap
+        Files:    <folder>/<name>.<ext>.abap    ← omit this line for XML-only types (TABL/STRU/DTEL/TTYP/DOMA/MSAG)
                   <folder>/<name>.<ext>.xml
 
       Shall I proceed?"
@@ -165,26 +179,27 @@ Anything else (SAP namespace object, or SAP-delivered package)?
 
 ---
 
-### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG, DDLS)
+### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG, DDLS, FUGR)
 
 ```
 ❌ WRONG: Make changes → Commit → Push → Pull → Find errors → Fix → Repeat
 ✅ CORRECT: Make changes → Run syntax → Fix locally → Commit → Push → Pull → Done
 ```
 
-**For CLAS, INTF, PROG, DDLS files**: Run `syntax` command BEFORE commit to catch errors early.
+**For CLAS, INTF, PROG, DDLS, FUGR files**: Run `syntax` command BEFORE commit to catch errors early.
 
 ```bash
 # Check syntax of local code (no commit/push needed)
 # Use the actual filename from your project (name comes from objects.local.md)
 abapgit-agent syntax --files src/<name>.clas.abap
 abapgit-agent syntax --files src/<name>.ddls.asddls
+abapgit-agent syntax --files src/<name>.fugr.<fm_name>.abap
 
 # Check multiple INDEPENDENT files
 abapgit-agent syntax --files src/<name1>.clas.abap,src/<name2>.clas.abap
 ```
 
-**For other types (FUGR, TABL, etc.)**: Skip syntax, proceed to commit/push/pull.
+**For other types (TABL, STRU, DCLS, etc.)**: Skip syntax, proceed to commit/push/pull.
 
 **Why use syntax command?**
 - Catches syntax errors BEFORE polluting git history with fix commits
@@ -410,7 +425,39 @@ After activating a class, stop and tell the user: `"Class is activated. Run with
 
 ---
 
-### 10. Probe and PoC Objects — Always Z/Y, Never in SAP Packages
+### 10. Never Run `drop` Command Without Explicit Permission
+
+**Never call `abapgit-agent drop` unless the user explicitly confirms.** Dropping an object physically deletes it from the ABAP system — this is irreversible without a subsequent pull.
+
+**When to SUGGEST `drop --pull`:**
+
+When an object is in a broken or inconsistent state that cannot be resolved by re-pulling:
+- `inspect` reports **"INCLUDE report ... not found"** (stale include in ABAP not present in git)
+- Pull repeatedly fails with **"Activation cancelled"** and re-pulling doesn't fix it
+- Object has a corrupt inactive version that permanently blocks activation
+
+In these cases, suggest the fix and wait for confirmation:
+
+```
+"The object ZCL_FOO has an inconsistent state (stale include in ABAP).
+ This can be fixed by dropping and re-pulling it:
+
+   abapgit-agent drop --files abap/zcl_foo.clas.abap --pull
+
+ This will delete ZCL_FOO from ABAP and immediately re-activate it from git.
+ Confirm when ready."
+```
+
+**What `drop --pull` does:**
+1. Physically deletes the object from the ABAP system
+2. Immediately re-pulls and re-activates it from git (clean state)
+3. Does NOT touch the git repository file
+
+**Constraint:** Only CLAS, INTF, PROG, TABL, TTYP are supported. DTEL (data elements) are rejected — edit the XML and use `pull` instead.
+
+---
+
+### 11. Probe and PoC Objects — Always Z/Y, Never in SAP Packages
 
 ```
 ❌ WRONG: Create a probe/PoC object with the project's SAP namespace prefix
@@ -436,7 +483,7 @@ Never assume — wait for the user's answer before proceeding.
 
 ---
 
-### 11. Troubleshooting ABAP Issues
+### 12. Troubleshooting ABAP Issues
 
 | Symptom | Tool | When |
 |---|---|---|
@@ -708,15 +755,18 @@ abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 
 ```
 Modified ABAP files?
-├─ CLAS/INTF/PROG/DDLS files?
+├─ CLAS/INTF/PROG/DDLS/FUGR files?
 │  ├─ Independent files (no cross-dependencies)?
 │  │  └─ ✅ Use: syntax → [abaplint] → commit → push → pull --sync-xml
 │  └─ Dependent files (interface + class, class uses class)?
 │     └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --sync-xml
-└─ Other types (FUGR, TABL, STRU, DTEL, TTYP, etc.)?
+└─ Other types (TABL, STRU, DTEL, TTYP, etc.)?
    ├─ XML-only objects (TABL, STRU, DTEL, TTYP, DOMA, MSAG)?
    │  └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files abap/ztable.tabl.xml --sync-xml
-   └─ FUGR and other complex objects?
+   ├─ DCLS (CDS access control)?
+   │  └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files abap/zc_view.dcls.xml --sync-xml
+   │         ⚠️  Pass the .xml file — pull --files does NOT accept .asdcls extensions
+   └─ Other complex objects?
       └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --sync-xml → (if errors: inspect)
 
 [abaplint] = run abapgit-agent lint only if .abaplint.json exists in repo root
@@ -736,6 +786,7 @@ Modified ABAP files?
 | `ref --topic exceptions` | Exception Handling |
 | `ref --topic classes` | ABAP Classes and Objects |
 | `ref --topic objects` | Object Naming Conventions (defaults) |
+| `ref --topic naming-limits` | Naming Length Limits — 30/16/40 char rules per type (CRITICAL before naming anything) |
 | `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) |
@@ -743,6 +794,7 @@ Modified ABAP files?
 | `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 string-template` | String Templates — syntax, escaping `\{` `\}`, JSON payloads |
 | `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 |

package/abap/guidelines/abapgit-fugr.md

@@ -22,10 +22,13 @@ A FUGR with group name `ZMY_FUGR` and one FM `ZMY_MY_FUNCTION` requires these fi
 | `zmy_fugr.fugr.xml` | Main XML: group description, includes list, FM interfaces |
 | `zmy_fugr.fugr.lzmy_fugrtop.abap` | TOP include source |
 | `zmy_fugr.fugr.lzmy_fugrtop.xml` | TOP include metadata (`SUBC=I`) |
-| `zmy_fugr.fugr.saplzmy_fugr.abap` | Main include source |
+| `zmy_fugr.fugr.saplzmy_fugr.abap` | Main include source (lists all U-includes) |
 | `zmy_fugr.fugr.saplzmy_fugr.xml` | Main include metadata (`SUBC=F`) |
+| `zmy_fugr.fugr.lzmy_fugru01.abap` | FM implementation include (one per FM: U01, U02, …) |
 | `zmy_fugr.fugr.zmy_my_function.abap` | FM source (one file per FM, named after FM in lowercase) |
 
+> **7 files total for one FM** (6 without the U01 include causes a pull error — the SAPL source references `LZMY_FUGRU01` which abapGit can't find). For a second FM, add `lzmy_fugru02.abap` and `zmy_second_function.abap`.
+
 ---
 
 ### `zmy_fugr.fugr.xml`
@@ -145,15 +148,28 @@ FUNCTION zmy_my_function.
 ENDFUNCTION.
 ```
 
+### `zmy_fugr.fugr.lzmy_fugru01.abap`
+
+The FM implementation include — **always required**. The SAPL source references `INCLUDE LZMY_FUGRU01.` so this file must exist or the pull fails.
+
+```abap
+*----------------------------------------------------------------------*
+***INCLUDE LZMY_FUGRU01.
+*----------------------------------------------------------------------*
+```
+
+For a second FM, create `zmy_fugr.fugr.lzmy_fugru02.abap` with the same pattern (replacing `U01` with `U02`).
+
 ---
 
 ## Key Rules
 
-- **Include naming**: TOP = `L<GROUP>TOP`, main = `SAPL<GROUP>` — uppercase in XML and filenames
+- **Include naming**: TOP = `L<GROUP>TOP`, main = `SAPL<GROUP>`, FM implementation = `L<GROUP>U01` (U02, U03, …) — uppercase in XML and filenames
 - **FM source file**: named after the FM in **lowercase** (`zmy_my_function.abap`, not `ZMY_MY_FUNCTION.abap`)
+- **U-include file required**: `lzmy_fugru01.abap` must exist — the SAPL source references it; missing it causes a pull error
 - **`INCLUDES` list** in the main XML: only lists TOP and SAPL includes — FM source includes are implicit
 - **`REMOTE_CALL>R`**: add only for RFC-enabled FMs; omit for local FMs
 - **Optional parameters**: include both `<OPTIONAL>X</OPTIONAL>` and `<DEFAULT>...</DEFAULT>`
-- **`DOCUMENTATION` section**: omit entirely if no parameter descriptions needed — missing docs cause no diff
+- **`DOCUMENTATION` section**: the serializer always writes `<DOCUMENTATION>` with one `<RSFDO>` entry per parameter (containing only `<PARAMETER>` and `<KIND>P</KIND>`, no `<STEXT>`). Always include it — omitting it causes a permanent "M" diff
 - **Screens/CUA**: omit `DYNPROS`/`CUA` sections for screenless function groups
 - **Multiple FMs**: add one `<item>` per FM in `FUNCTIONS`; add one `INCLUDE` line per FM in the SAPL source

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

@@ -170,6 +170,12 @@ A **text table** stores translatable texts for another table (the "main table").
 
 > Pull with: `pull --files src/zmy_dtel.dtel.xml`
 
+**Two variants — choose based on whether the DTEL defines its own type or references a domain:**
+
+#### Variant 1: Built-in type (no domain)
+
+Use when the data element directly defines `DATATYPE` and `LENG` without referencing a domain.
+
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_DTEL" serializer_version="v1.0.0">
@@ -192,13 +198,38 @@ A **text table** stores translatable texts for another table (the "main table").
 </abapGit>
 ```
 
+#### Variant 2: Domain reference
+
+Use when the data element's type and length come from an existing domain (`DOMNAME`). Do **not** include `DATATYPE` or `LENG` — the domain owns those.
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_DTEL" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <DD04V>
+    <ROLLNAME>ZMY_DTEL</ROLLNAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <DDTEXT>Description of data element</DDTEXT>
+    <REPTEXT>Description</REPTEXT>
+    <SCRTEXT_S>Short text</SCRTEXT_S>
+    <SCRTEXT_M>Medium text</SCRTEXT_M>
+    <SCRTEXT_L>Long description text</SCRTEXT_L>
+    <DTELMASTER>E</DTELMASTER>
+    <DOMNAME>ZMY_DOMAIN</DOMNAME>
+   </DD04V>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
 **Key Fields**:
 - `ROLLNAME`: Data element name
 - `DDTEXT`: Description (**not** `DESCRIPT`)
 - `REPTEXT` / `SCRTEXT_S` / `SCRTEXT_M` / `SCRTEXT_L`: Field labels (report heading, short, medium, long)
 - `DTELMASTER`: Language key for label master (`E` for English)
-- `DATATYPE`: Data type (`CHAR`, `NUMC`, `DATS`, `TIMS`, `INT4`, etc.)
-- `LENG`: Length padded to 6 digits (e.g. `000010` for 10 characters)
+- `DATATYPE` + `LENG`: Use for built-in type variant only (e.g. `CHAR` + `000010`)
+- `DOMNAME`: Use for domain-reference variant only — omit `DATATYPE` and `LENG` entirely
 
 **Omit `<PARAMID>`** unless you specifically need a SET/GET parameter ID — the serializer omits it when empty.
 
@@ -206,10 +237,14 @@ A **text table** stores translatable texts for another table (the "main table").
 
 ### Structure (STRU)
 
-**Filename**: `src/zmy_struct.stru.xml`
+**Filename**: `src/zmy_struct.tabl.xml`
 
-> abapGit uses the same TABL serializer for STRU.
-> Pull with: `pull --files src/zmy_struct.stru.xml`
+> ⚠️ **Use `.tabl.xml` extension, NOT `.stru.xml`** — abapGit serializes structures with the TABL
+> serializer and registers them as object type `TABL`. A `.stru.xml` filename causes
+> "Step DDIC is only for DDIC objects" because abapGit treats it as object type `STRU`,
+> which is not in its DDIC activation list.
+>
+> Pull with: `pull --files src/zmy_struct.tabl.xml`
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -221,16 +256,37 @@ A **text table** stores translatable texts for another table (the "main table").
     <DDLANGUAGE>E</DDLANGUAGE>
     <TABCLASS>INTTAB</TABCLASS>
     <DDTEXT>Description of the structure</DDTEXT>
-    <CONTFLAG>A</CONTFLAG>
+    <EXCLASS>1</EXCLASS>
    </DD02V>
+   <DD03P_TABLE>
+    <DD03P>
+     <FIELDNAME>FIELD1</FIELDNAME>
+     <ROLLNAME>S_CARR_ID</ROLLNAME>
+     <ADMINFIELD>0</ADMINFIELD>
+     <SHLPORIGIN>D</SHLPORIGIN>
+     <COMPTYPE>E</COMPTYPE>
+    </DD03P>
+    <DD03P>
+     <FIELDNAME>FIELD2</FIELDNAME>
+     <ROLLNAME>S_CARRNAME</ROLLNAME>
+     <ADMINFIELD>0</ADMINFIELD>
+     <COMPTYPE>E</COMPTYPE>
+    </DD03P>
+   </DD03P_TABLE>
   </asx:values>
  </asx:abap>
 </abapGit>
 ```
 
-**Key difference from TABL**: `TABCLASS` is `INTTAB` (internal table / structure) instead of `TRANSP`.
+**Key differences from TABL**:
+- `TABCLASS` is `INTTAB` instead of `TRANSP`
+- No `<CONTFLAG>` — omit it (not written by serializer for structures)
+- `<EXCLASS>1</EXCLASS>` — include it
+- Include `<DD03P_TABLE>` with field definitions from the start (unlike TABL where it is optional on creation)
 
-**Note**: Like TABL, after the first pull abapGit expands the XML with `<DD03P_TABLE>` field definitions.
+**`DD03P` field rules** (same as TABL):
+- Fields with `ROLLNAME` (data element): include `ROLLNAME`, `ADMINFIELD>0`, `SHLPORIGIN` (when domain provides value help — `D` for domain fixed values), `COMPTYPE>E`
+- Fields with raw type (no data element): include `ADMINFIELD>0`, `INTTYPE`, `INTLEN`, `DATATYPE`, `MASK` (before any text fields)
 
 ---
 
@@ -248,13 +304,13 @@ A **text table** stores translatable texts for another table (the "main table").
    <DD40V>
     <TYPENAME>ZMY_TTYP</TYPENAME>
     <DDLANGUAGE>E</DDLANGUAGE>
-    <DDTEXT>Description of table type</DDTEXT>
     <ROWTYPE>ZMY_STRUCT</ROWTYPE>
     <ROWKIND>S</ROWKIND>
-    <DATATYPE>TABLE_T</DATATYPE>
+    <DATATYPE>STRU</DATATYPE>
     <ACCESSMODE>T</ACCESSMODE>
     <KEYDEF>D</KEYDEF>
     <KEYKIND>N</KEYKIND>
+    <DDTEXT>Description of table type</DDTEXT>
    </DD40V>
   </asx:values>
  </asx:abap>
@@ -265,7 +321,7 @@ A **text table** stores translatable texts for another table (the "main table").
 - `TYPENAME`: Table type name
 - `ROWTYPE`: Row type (a structure or data element name)
 - `ROWKIND`: Row kind — `S`=Structure/Type, `D`=Data element, `R`=Reference
-- `DATATYPE`: Always `TABLE_T` for table types
+- `DATATYPE`: `STRU` when row type is a structure (`ROWKIND=S`); `TABLE_T` only for elementary-type row types
 - `ACCESSMODE`: Table kind — `T`=Standard, `S`=Sorted, `H`=Hashed
 - `KEYDEF`: Key definition — `D`=Default (standard key), `K`=User-defined
 - `KEYKIND`: Key uniqueness — `N`=Non-unique, `U`=Unique
@@ -372,7 +428,7 @@ abapGit uses the view `DD01V` as the root element (not `DD01L`). The serializer
      <SPRSL>E</SPRSL>
      <ARBGB>ZMY_MSGS</ARBGB>
      <MSGNR>000</MSGNR>
-     <TEXT>Object &1 not found</TEXT>
+     <TEXT>Object &amp;1 not found</TEXT>
     </T100>
     <T100>
      <SPRSL>E</SPRSL>

package/abap/guidelines/abapgit.md

@@ -265,7 +265,7 @@ abapGit's serializer **omits fields that have their default value**. Writing ext
 - `SOURCE_TYPE W` → View Entity (`define view entity`, modern — **use by default**)
 - `SOURCE_TYPE V` → View (`define view` + `@AbapCatalog.sqlViewName`, legacy)
 
-→ For DDL source syntax: `abapgit-agent ref --topic cds-abapgit`
+→ For DDL source syntax: `abapgit-agent ref --topic cds`
 
 ---
 
@@ -290,6 +290,7 @@ abapGit's serializer **omits fields that have their default value**. Writing ext
 
 - `DCLNAME` matches the CDS view name
 - Source file contains the DCL (`@MappingRole ... define role ...`)
+- **Pull with the `.xml` file, not `.asdcls`**: `pull --files src/zc_my_view.dcls.xml` — the `pull --files` filter does not accept `.asdcls` extensions
 
 ---
 

package/abap/guidelines/abaplint.md

@@ -80,6 +80,41 @@ lv_response = lv_response && '"key":"val"}'.
 | `DATA(lv) = 'literal'.` followed by `&&` | ❌ | Infers `C LENGTH N`, truncates |
 | `DATA(lv) = 'literal'.` used only in `\|{ lv }\|` | ⚠️ | Technically works but misleading — prefer explicit type |
 | `DATA(lv) = 'X'.` used as abap_bool flag | ✅ | `C LENGTH 1` is correct for flags |
+| `DATA(lv) = COND string( WHEN ... THEN str+off ELSE str ).` | ❌ | Offset notation on `string` inside COND raises `CX_SY_RANGE_OUT_OF_BOUNDS` at runtime |
+
+### The offset-notation-in-COND trap
+
+Offset/length notation (`str+off` or `str(len)`) on a `string`-typed variable **cannot appear
+as a result expression inside `COND`** — even when the `COND` is explicitly typed as `string`.
+ABAP evaluates both branch types at generation time and the offset expression on a dynamic
+string is invalid, causing a `CX_SY_RANGE_OUT_OF_BOUNDS` crash at runtime.
+
+```abap
+DATA lv_file TYPE string VALUE 'src/foo.clas.abap'.
+DATA(lv_pos) = find( val = lv_file sub = '/' occ = -1 ).
+
+* WRONG — CX_SY_RANGE_OUT_OF_BOUNDS at runtime
+DATA(lv_path) = COND string(
+  WHEN lv_pos > 0 THEN '/' && lv_file(lv_pos + 1)   " ← offset on string = crash
+  ELSE '/' ).
+
+* CORRECT — use substring() which returns string and is safe in COND
+DATA(lv_path) = COND string(
+  WHEN lv_pos > 0 THEN '/' && substring( val = lv_file len = lv_pos + 1 )
+  ELSE '/' ).
+
+* ALSO CORRECT — keep IF/ELSE with DATA x TYPE string
+DATA lv_path TYPE string.
+IF lv_pos > 0.
+  DATA(lv_len) = lv_pos + 1.
+  lv_path = '/' && lv_file(lv_len).
+ELSE.
+  lv_path = '/'.
+ENDIF.
+```
+
+**Rule**: whenever the prefer_inline quickfix would produce `COND ... THEN str+off` or
+`COND ... THEN str(len)`, use `substring()` instead, or keep the `IF/ELSE` form.
 
 ### Rule of thumb
 

package/abap/guidelines/common-errors.md

@@ -8,7 +8,7 @@ grand_parent: ABAP Development
 
 # Common ABAP Errors - Quick Fixes
 
-**Searchable keywords**: error, syntax error, field mismatch, fixed point, comma, host variable, @ prefix, type incompatible
+**Searchable keywords**: error, syntax error, field mismatch, fixed point, comma, host variable, @ prefix, type incompatible, string template, expression limiter, literal brace, http 500, xml metadata mismatch, interface description, descript, recompilation, offset notation, cond trap, cx_sy_range_out_of_bounds
 
 ## Fixed Point Arithmetic Error
 
@@ -119,6 +119,83 @@ or declare the variable explicitly with `TYPE string`.
 
 ---
 
+## Offset Notation on String in COND — CX_SY_RANGE_OUT_OF_BOUNDS
+
+**Symptom**: Pull succeeds but ABAP crashes at runtime with `CX_SY_RANGE_OUT_OF_BOUNDS`
+inside a method using `COND`.
+
+**Root cause**: Offset/length notation on a `string` variable (`str+off`, `str(len)`)
+**cannot be used as a result expression inside `COND`** — even with an explicit `COND string(...)` type.
+The abaplint `prefer_inline` quickfix can introduce this automatically when converting
+an `IF/ELSE` block that assigns from a string-variable offset.
+
+```abap
+* WRONG — crashes at runtime with CX_SY_RANGE_OUT_OF_BOUNDS
+DATA(lv_path) = COND string(
+  WHEN lv_pos > 0 THEN '/' && lv_file(lv_pos + 1)   " ← string offset in COND
+  ELSE '/' ).
+
+* CORRECT — use substring() instead
+DATA(lv_path) = COND string(
+  WHEN lv_pos > 0 THEN '/' && substring( val = lv_file len = lv_pos + 1 )
+  ELSE '/' ).
+```
+
+**Fix**: Replace `str+off` / `str(len)` inside `COND` results with `substring( val = str off = off )` or
+`substring( val = str len = len )`, or revert to the `IF/ELSE` form with `DATA x TYPE string`.
+
+→ See `abaplint.md` for the full safe/unsafe table for `prefer_inline`.
+
+---
+
+## XML Metadata Mismatch — HTTP 500 on Pull
+
+**Symptom**: `pull` returns HTTP 500 with no short dump (ST22) for the request user.
+Other objects pull fine; only a specific interface or class fails.
+
+**Root cause**: The `.intf.xml` or `.clas.xml` file in git has a metadata field (e.g. `DESCRIPT`,
+`UNICODE`, `STATE`) that differs from the active ABAP system value. abapGit writes the git
+value back to VSEOINTERF/VSEOCLASS, which forces the SAP class framework to recompile all
+implementing/inheriting objects. If any implementing class has a syntax or generation
+issue with the current active source, the recompilation crashes outside the normal exception
+handler — producing HTTP 500 with no dump.
+
+**Diagnosis**:
+1. No dump in ST22 for your user → not a user-code crash
+2. Only one specific INTF/CLAS fails → metadata delta in its XML triggers recompilation
+3. Check what differs: `abapgit-agent view --objects ZIF_MY_INTF --type INTF` and compare
+   `DESCRIPT` / other fields with the XML file in git
+
+**Fix**: Sync the XML to match the ABAP system value. The easiest way:
+
+```bash
+# Pull without --sync-xml first to let abapGit rewrite the XML from the system
+abapgit-agent pull --files abap/zif_my_intf.intf.abap --sync-xml
+```
+
+Or manually correct the field in the XML file to match the system value, then push and pull.
+
+**Prevention**: Always use `--sync-xml` after pulling new objects so the XML stays in sync
+with what the ABAP serializer produces.
+
+---
+
+**Error**: `Expression limiter '{' in string template not followed by space`
+
+Literal `{` and `}` (e.g. in JSON payloads) must be escaped as `\{` and `\}` inside `|...|`.
+
+```abap
+" WRONG — unescaped { in JSON triggers parse error
+rv_result = |{"success":"X","name":"{ lv_name }"}|.
+
+" CORRECT
+rv_result = |\{"success":"X","name":"{ lv_name }"\}|.
+```
+
+→ Full escaping rules and examples: `abapgit-agent ref --topic string-template`
+
+---
+
 ## See Also
 - **ABAP SQL** (sql.md) - for SQL syntax rules
 - **CDS Views** (cds.md) - for CDS selection patterns

package/abap/guidelines/index.md

@@ -20,6 +20,7 @@ This folder contains detailed ABAP coding guidelines that can be searched using
 | `cds.md` | CDS Views |
 | `classes.md` | ABAP Classes and Objects |
 | `objects.md` | Object Naming Conventions |
+| `naming-limits.md` | Naming Length Limits (30/16/40 char rules per type) |
 | `json.md` | JSON Handling |
 | `abapgit.md` | abapGit XML Metadata Templates |
 | `unit-testable-code.md` | Unit Testable Code Guidelines (Dependency Injection) |