abapgit-agent 1.13.2 → 1.13.4

package/abap/CLAUDE.md

@@ -70,24 +70,93 @@ abapgit-agent ref --list-topics
 ```
 
 The folder is configured in `.abapGitAgent` (property: `folder`):
-- If `folder` is `/src/` → files go in `src/` (e.g., `src/zcl_my_class.clas.abap`)
-- If `folder` is `/abap/` → files go in `abap/` (e.g., `abap/zcl_my_class.clas.abap`)
+- If `folder` is `/src/` → files go in `src/`
+- If `folder` is `/abap/` → files go in `abap/`
 
 **Also check naming conventions before creating any new object:**
 
 ```
-1. Check guidelines/objects.local.md  ← project-specific overrides (if file exists)
-2. Fall back to guidelines/objects.md ← default Z/Y prefix conventions
+1. Check guidelines/objects.local.md  ← this project's actual conventions (if file exists)
+2. No objects.local.md?               ← customer namespace project, use Z/Y defaults
 ```
 
-`objects.local.md` is created by `abapgit-agent init` and is never overwritten by updates — it holds project-specific prefixes (e.g. `YCL_` instead of `ZCL_`).
+`objects.local.md` is never overwritten by updates. It specifies the production naming
+pattern — which may be customer namespace (`ZCL_*`, `YCL_*`), SAP namespace (`CL_*`),
+or SAP registered namespace (`/NAMESPACE/CL_*` — also SAP namespace, not customer).
+Never assume Z/Y prefix without checking.
+
+**SAP namespace vs customer namespace:**
+- **Customer namespace**: `Z*`, `Y*` objects; `Z*`, `Y*`, `$*` packages — owned by the customer
+- **SAP namespace**: everything else (`CL_*`, `IF_*`, `/NAMESPACE/*`) — delivered by SAP
 
 ---
 
-### 3. Create XML Metadata / Local Classes
+### 3. Creating a New ABAP Object — Files to Write and Package Assignment
 
-Each ABAP object needs an XML metadata file. Local helper/test-double classes use separate `.locals_def.abap` / `.locals_imp.abap` files.
-→ See `guidelines/object-creation.md` — run: `abapgit-agent ref --topic object-creation`
+```
+❌ WRONG: Only write the .abap source file
+✅ CORRECT: Every object needs both a source file AND an XML metadata file
+           XML-only objects (TABL, STRU, DTEL, TTYP) need ONLY the XML file
+```
+
+Use the object name from `objects.local.md` (or `objects.md` as fallback) in place of `<name>`:
+
+| Object Type | Source File | XML File |
+|-------------|-------------|----------|
+| Class (CLAS) | `<name>.clas.abap` | `<name>.clas.xml` |
+| Interface (INTF) | `<name>.intf.abap` | `<name>.intf.xml` |
+| Program (PROG) | `<name>.prog.abap` | `<name>.prog.xml` |
+| CDS View (DDLS) | `<name>.ddls.asddls` | `<name>.ddls.xml` |
+| Table (TABL) | *(none)* | `<name>.tabl.xml` |
+| Structure (STRU) | *(none)* | `<name>.stru.xml` |
+| Data Element (DTEL) | *(none)* | `<name>.dtel.xml` |
+| Table Type (TTYP) | *(none)* | `<name>.ttyp.xml` |
+
+**Package assignment — determine the package, then follow the confirmation rule below:**
+
+```
+1. Check objects.local.md for package rules  ← use them directly
+2. No package rules in objects.local.md?
+   └── Read .abapGitAgent → get the package property → use as root
+       Run: abapgit-agent tree --package <root>
+       ├── Only one package found   →  use it directly
+       └── Multiple packages found  →  present options, ask user to choose
+3. No package in .abapGitAgent?
+   └── Ask the user for the root package
+```
+
+**Confirmation before writing files — depends on namespace:**
+
+```
+Object name starts with Z* or Y*  AND  package starts with Z*, Y*, or $*?
+  └── Customer namespace object in customer package
+      → Write files directly. No confirmation needed.
+
+Anything else (SAP namespace object, or SAP-delivered package)?
+  └── Show a creation summary and wait for explicit confirmation:
+
+      "I'm going to create the following:
+
+        Object:   <NAME> (<Type>)
+        Package:  <PACKAGE>
+        Files:    <folder>/<name>.<ext>.abap
+                  <folder>/<name>.<ext>.xml
+
+      Shall I proceed?"
+```
+
+```
+❌ WRONG: Write files without showing the summary for SAP namespace objects
+❌ WRONG: Run abapgit-agent tree and pick a package yourself
+✅ CORRECT: Customer namespace → write directly
+✅ CORRECT: SAP namespace → always show summary, wait for confirmation
+```
+
+> **Tip for project setup**: Add package rules to `objects.local.md` so Claude never
+> needs to ask. See `guidelines/objects.md` for examples.
+
+→ For exact XML templates: `abapgit-agent ref --topic abapgit`
+→ For local helper/test-double class files: `abapgit-agent ref --topic object-creation`
 
 ---
 
@@ -102,14 +171,15 @@ Each ABAP object needs an XML metadata file. Local helper/test-double classes us
 
 ```bash
 # Check syntax of local code (no commit/push needed)
-abapgit-agent syntax --files src/zcl_my_class.clas.abap
-abapgit-agent syntax --files src/zc_my_view.ddls.asddls
+# 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
 
 # Check multiple INDEPENDENT files
-abapgit-agent syntax --files src/zcl_utils.clas.abap,src/zcl_logger.clas.abap
+abapgit-agent syntax --files src/<name1>.clas.abap,src/<name2>.clas.abap
 ```
 
-**For other types (DDLS, FUGR, TABL, etc.)**: Skip syntax, proceed to commit/push/pull.
+**For other types (FUGR, TABL, etc.)**: Skip syntax, proceed to commit/push/pull.
 
 **Why use syntax command?**
 - Catches syntax errors BEFORE polluting git history with fix commits
@@ -126,11 +196,11 @@ When checking multiple files, each is validated in isolation:
 **For dependent files, skip `syntax` and use `pull` instead:**
 ```bash
 # ❌ BAD - Interface and implementing class (may show false errors)
-abapgit-agent syntax --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
+abapgit-agent syntax --files src/<intf_name>.intf.abap,src/<class_name>.clas.abap
 
 # ✅ GOOD - Use pull instead for dependent files
 git add . && git commit && git push
-abapgit-agent pull --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
+abapgit-agent pull --files src/<intf_name>.intf.abap,src/<class_name>.clas.abap
 ```
 
 **Note**: `inspect` still runs against ABAP system (requires pull first). Use `syntax` for pre-commit checking.
@@ -256,11 +326,29 @@ After activating a class, stop and tell the user: `"Class is activated. Run with
 
 ---
 
-### 10. Probe Classes — Use `scratchWorkspace` When Required
+### 10. Probe and PoC Objects — Always Z/Y, Never in SAP Packages
+
+```
+❌ WRONG: Create a probe/PoC object with the project's SAP namespace prefix
+❌ WRONG: Assign a probe/PoC object to an SAP-delivered package
+✅ CORRECT: Probe/PoC objects always use Z* or Y* prefix
+✅ CORRECT: Always assign to a customer namespace package (Z*, Y*, or $*)
+```
+
+This rule applies even on projects where production objects use SAP namespace (`CL_*`, `/NAMESPACE/*`).
+
+**Trigger — when `objects.local.md` shows a SAP namespace prefix (`CL_*`, `IF_*`, `/NAMESPACE/*`)
+and the user asks to create a new object, always ask first:**
+
+```
+"Is this a production object, a PoC (will persist, needs its own package/repo),
+ or a probe (throwaway, run once)?"
+```
 
-By default, probe/throwaway classes may be created in the current project. When `disableProbeClasses: true` is set in `.abapgit-agent.json`, they must go to `scratchWorkspace` instead. If `scratchWorkspace` is also not configured, refuse and guide the user to set it up.
+Never assume — wait for the user's answer before proceeding.
 
-→ See `guidelines/run-probe-classes.md` — run: `abapgit-agent ref --topic run-probe-classes`
+→ For full decision flow (how to determine namespace, probe vs PoC, scratchWorkspace,
+  pocWorkspace, setup instructions): `abapgit-agent ref --topic probe-poc`
 
 ---
 
@@ -355,11 +443,11 @@ If workflow mode is `"trunk"` or not set, commit directly to the default branch:
 ```bash
 git checkout main  # or master/develop (auto-detected)
 git pull origin main
-edit src/zcl_auth_handler.clas.abap
-abapgit-agent syntax --files src/zcl_auth_handler.clas.abap
-git add . && git commit -m "feat: add authentication handler"
+# edit your ABAP file (name from objects.local.md)
+abapgit-agent syntax --files src/<name>.clas.abap
+git add . && git commit -m "feat: description"
 git push origin main
-abapgit-agent pull --files src/zcl_auth_handler.clas.abap
+abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 ```
 
 ### AI Tool Guidelines
@@ -400,7 +488,14 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap
 2. ✓ Inform the user that run is disabled for this project
 
 **When `safeguards.disableProbeClasses = true`:**
-1. ✗ Do not create probe classes in the current project — see Rule 10 and `guidelines/run-command.md`
+1. ✗ Do not create probe classes in the current project
+2. ✓ If `scratchWorkspace` is configured → create probe class there (see Rule 10)
+3. ✗ If `scratchWorkspace` is NOT configured → refuse, tell user to configure it in `.abapGitAgent`
+
+**When user requests a PoC object:**
+1. ✓ Read `pocWorkspace.path` from `.abapGitAgent`
+2. ✓ If configured → read `{path}/.abapGitAgent` for package, show confirmation summary, wait for user
+3. ✗ If NOT configured → refuse, tell user to set up a PoC repo and configure `pocWorkspace.path`
 
 **When `conflictDetection.mode = "ignore"` or not set:**
 1. ✓ Run `pull` normally — no conflict flags needed
@@ -425,6 +520,11 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap
 1. ✗ Do not run `abapgit-agent transport release`
 2. ✓ Inform the user that transport release is disabled for this project
 
+**After every pull that creates or modifies ABAP objects:**
+1. ✓ Always pass `--sync-xml` — rewrites any XML metadata files that differ from the ABAP serializer output, amends the commit, and re-pulls so git and the ABAP system stay in sync
+2. ✓ If pull output shows `⚠️  X XML file(s) differ from serializer output`, re-run immediately with `--sync-xml`
+3. ✗ Never leave a pull without `--sync-xml` when you authored the objects — abapGit will show **M (modified)** permanently otherwise
+
 ---
 
 ### Quick Decision Tree for AI
@@ -435,13 +535,17 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap
 Modified ABAP files?
 ├─ CLAS/INTF/PROG/DDLS files?
 │  ├─ Independent files (no cross-dependencies)?
-│  │  └─ ✅ Use: syntax → commit → push → pull
+│  │  └─ ✅ Use: syntax → commit → push → pull --sync-xml
 │  └─ Dependent files (interface + class, class uses class)?
-│     └─ ✅ Use: skip syntax → commit → push → pull
-└─ Other types (DDLS, FUGR, TABL, etc.)?
-   └─ ✅ Use: skip syntax → commit → push → pull → (if errors: inspect)
+│     └─ ✅ Use: skip syntax → commit → push → pull --sync-xml
+└─ Other types (FUGR, TABL, STRU, DTEL, TTYP, etc.)?
+   ├─ XML-only objects (TABL, STRU, DTEL, TTYP)?
+   │  └─ ✅ Use: skip syntax → commit → push → pull --files abap/ztable.tabl.xml --sync-xml
+   └─ FUGR and other complex objects?
+      └─ ✅ Use: skip syntax → commit → push → pull --sync-xml → (if errors: inspect)
 ```
 
+→ 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`
 
 ---
@@ -474,6 +578,7 @@ Detailed guidelines are available in the `guidelines/` folder:
 | `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) |

package/abap/CLAUDE.slim.md

@@ -10,6 +10,8 @@ Read the full ABAP development guide by running:
 abapgit-agent guide
 ```
 
+**Never pipe `abapgit-agent guide` or `abapgit-agent ref` through `head`, `tail`, or any other truncation command. Always read the full output.**
+
 This guide covers: development workflow, ABAP syntax guidelines, object naming, unit testing, and debugging.
 
 > **Humans:** Full guide online at https://sylvoscai.github.io/abapgit-agent/pages/abap-coding-guidelines.html

package/abap/guidelines/abapgit.md

@@ -19,23 +19,23 @@ Class              | zcl_*.clas.abap              | zcl_*.clas.xml
 Test Class         | zcl_*.clas.testclasses.abap | zcl_*.clas.xml
 Interface          | zif_*.intf.abap             | zif_*.intf.xml
 Program            | z*.prog.abap                | z*.prog.xml
-Table              | z*.tabl.abap                | z*.tabl.xml
 CDS View (DDLS)    | zc_*.ddls.asddls            | zc_*.ddls.xml
-Data Element       | z*.dtel.abap                | z*.dtel.xml
-Structure          | z*.stru.abap                | z*.stru.xml
-Table Type         | z*.ttyp.abap                | z*.ttyp.xml
+Table (TABL)       | (no .abap file)             | z*.tabl.xml
+Structure (STRU)   | (no .abap file)             | z*.stru.xml
+Data Element (DTEL)| (no .abap file)             | z*.dtel.xml
+Table Type (TTYP)  | (no .abap file)             | z*.ttyp.xml
 ```
 
-```
-Key XML Settings:
-  Class EXPOSURE:   2=Public, 3=Protected, 4=Private
-  Class STATE:      1=Active
-  Table TABCLASS:   TRANSP, POOL, CLUSTER
-  Table DELIVERY:   A=Application, C=Customizing
-  CDS SOURCE_TYPE:  W=View Entity (modern), V=View (legacy)
-  Test Class XML:   <WITH_UNIT_TESTS>X</WITH_UNIT_TESTS>
-  Local Classes:    <CLSCCINCL>X</CLSCCINCL>
-```
+> **XML-only objects (TABL, STRU, DTEL, TTYP)** have **no ABAP source file**. abapGit serializes
+> them as XML metadata only. When using `--files`, pass the `.xml` file directly:
+> `abapgit-agent pull --files abap/zmy_table.tabl.xml --sync-xml`
+
+> **CRITICAL: Always write XML files with a UTF-8 BOM (`\ufeff`) as the very first character**, before `<?xml ...`.
+> Without the BOM, abapGit shows the object as **"M" (modified)** after every pull because the
+> serializer always produces XML with BOM — and every byte matters.
+
+> **CRITICAL: Only include fields that abapGit's serializer actually writes. Never add fields with
+> default values.** Extra fields cause a permanent "M" (modified) diff. Follow the exact templates below.
 
 **Searchable keywords**: class xml, interface xml, table xml, cds xml, test class, exposure, serializer, abapgit
 
@@ -46,14 +46,50 @@ abapGit needs XML files to:
 - Store object attributes (description, exposure, state, etc.)
 - Handle object-specific configurations
 
+## Field Presence Rules (CRITICAL)
+
+abapGit's serializer **omits fields that have their default value**. Writing extra fields causes permanent
+"M" (modified) status in abapGit UI. Follow these rules strictly:
+
+### CLAS — Field Presence Rules
+
+| Field | Include when | Omit when |
+|---|---|---|
+| `CLSNAME` | Always | — |
+| `LANGU` | Always | — |
+| `DESCRIPT` | Always | — |
+| `CATEGORY` | Non-standard class (`40`=exception, `05`=test double) | Standard class (default `00`) — **omit** |
+| `EXPOSURE` | **Never for CLAS** | **Always omit** — public (`2`) is the default and is never written |
+| `STATE` | Always (`1`) | — |
+| `CLSCCINCL` | `.clas.locals_def.abap` file exists | No local class files — **omit** |
+| `FIXPT` | Always (`X`) | — |
+| `UNICODE` | Always (`X`) | — |
+| `WITH_UNIT_TESTS` | `.clas.testclasses.abap` file exists | No test class file — **omit** |
+| `MSG_ID` | Class has a message class | No message class — **omit** |
+
+**Field order**: `CLSNAME → LANGU → DESCRIPT → [CATEGORY] → STATE → [CLSCCINCL] → FIXPT → UNICODE → [WITH_UNIT_TESTS] → [MSG_ID]`
+
+### INTF — Field Presence Rules
+
+| Field | Include when | Omit when |
+|---|---|---|
+| `CLSNAME` | Always | — |
+| `LANGU` | Always | — |
+| `DESCRIPT` | Always | — |
+| `EXPOSURE` | Always (`2`) | — (interfaces always have EXPOSURE, unlike classes) |
+| `STATE` | Always (`1`) | — |
+| `UNICODE` | Always (`X`) | — |
+
 ## Object Types and XML Templates
 
 ### Class (CLAS)
 
 **Filename**: `src/zcl_my_class.clas.xml`
 
+**Standard public class** (no local includes, no test class):
+
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_CLAS" serializer_version="v1.0.0">
  <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
   <asx:values>
@@ -61,29 +97,85 @@ abapGit needs XML files to:
     <CLSNAME>ZCL_MY_CLASS</CLSNAME>
     <LANGU>E</LANGU>
     <DESCRIPT>Description of the class</DESCRIPT>
-    <EXPOSURE>2</EXPOSURE>
     <STATE>1</STATE>
+    <FIXPT>X</FIXPT>
     <UNICODE>X</UNICODE>
+   </VSEOCLASS>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Class with test class** (`.clas.testclasses.abap` exists — add `WITH_UNIT_TESTS`):
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_CLAS" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <VSEOCLASS>
+    <CLSNAME>ZCL_MY_CLASS</CLSNAME>
+    <LANGU>E</LANGU>
+    <DESCRIPT>Description of the class</DESCRIPT>
+    <STATE>1</STATE>
     <FIXPT>X</FIXPT>
+    <UNICODE>X</UNICODE>
+    <WITH_UNIT_TESTS>X</WITH_UNIT_TESTS>
    </VSEOCLASS>
   </asx:values>
  </asx:abap>
 </abapGit>
 ```
 
-**Key Fields**:
-- `CLSNAME`: Class name (must match filename)
-- `DESCRIPT`: Class description
-- `EXPOSURE`: Exposure (2 = Public, 3 = Protected, 4 = Private)
-- `STATE`: State (1 = Active)
-- `UNICODE`: Unicode encoding (X = Yes)
-- `FIXPT`: Fixed-point arithmetic (X = Yes) - **Always include for correct decimal arithmetic**
+**Class with local includes** (`.clas.locals_def.abap` exists — add `CLSCCINCL` before `FIXPT`):
 
-**Note**: `<FIXPT>X</FIXPT>` is default for modern ABAP. Without it, decimals treated as integers.
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_CLAS" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <VSEOCLASS>
+    <CLSNAME>ZCL_MY_CLASS</CLSNAME>
+    <LANGU>E</LANGU>
+    <DESCRIPT>Description of the class</DESCRIPT>
+    <STATE>1</STATE>
+    <CLSCCINCL>X</CLSCCINCL>
+    <FIXPT>X</FIXPT>
+    <UNICODE>X</UNICODE>
+    <WITH_UNIT_TESTS>X</WITH_UNIT_TESTS>
+   </VSEOCLASS>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
 
-**Local Classes**: If the class has local classes (e.g., test doubles), add:
-- `<WITH_UNIT_TESTS>X</WITH_UNIT_TESTS>` - for test classes
-- `<CLSCCINCL>X</CLSCCINCL>` - for local class definitions
+**Exception class** (`CATEGORY>40` — add `CATEGORY` after `DESCRIPT`):
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_CLAS" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <VSEOCLASS>
+    <CLSNAME>ZCX_MY_EXCEPTION</CLSNAME>
+    <LANGU>E</LANGU>
+    <DESCRIPT>My exception</DESCRIPT>
+    <CATEGORY>40</CATEGORY>
+    <STATE>1</STATE>
+    <CLSCCINCL>X</CLSCCINCL>
+    <FIXPT>X</FIXPT>
+    <UNICODE>X</UNICODE>
+   </VSEOCLASS>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key rules**:
+- ❌ **Never include `<EXPOSURE>`** in a CLAS XML — public (2) is the default and abapGit omits it
+- ✅ Always include `<FIXPT>X</FIXPT>` and `<UNICODE>X</UNICODE>`
+- ✅ Add `<WITH_UNIT_TESTS>X</WITH_UNIT_TESTS>` only when `.clas.testclasses.abap` exists
+- ✅ Add `<CLSCCINCL>X</CLSCCINCL>` only when `.clas.locals_def.abap` exists
 
 **Local Class Files**:
 | File | Purpose |
@@ -98,7 +190,7 @@ abapGit needs XML files to:
 **Filename**: `src/zif_my_interface.intf.xml`
 
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_INTF" serializer_version="v1.0.0">
  <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
   <asx:values>
@@ -115,6 +207,9 @@ abapGit needs XML files to:
 </abapGit>
 ```
 
+**Key rules**:
+- ✅ `<EXPOSURE>2</EXPOSURE>` is **always present** for interfaces (unlike classes where it is omitted)
+
 ---
 
 ### Program (PROG)
@@ -122,13 +217,13 @@ abapGit needs XML files to:
 **Filename**: `src/zmy_program.prog.xml`
 
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_PROG" serializer_version="v1.0.0">
  <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
   <asx:values>
    <PROGDIR>
     <NAME>ZMY_PROGRAM</NAME>
-    <SUBC>I</SUBC>
+    <SUBC>1</SUBC>
     <RLOAD>E</RLOAD>
     <FIXPT>X</FIXPT>
     <UCCHECK>X</UCCHECK>
@@ -140,8 +235,12 @@ abapGit needs XML files to:
 
 **Key Fields**:
 - `NAME`: Program name
-- `SUBC`: Subc (I = Include, 1 = Executable, F = Function Group, M = Module Pool, S = Subroutine Pool)
-- `RLOAD`: Rload (E = External, I = Internal)
+- `SUBC`: Program type (`1`=Executable, `I`=Include, `F`=Function Group, `M`=Module Pool, `S`=Subroutine Pool)
+- `RLOAD`: `E`=External
+- `FIXPT`: Fixed-point arithmetic (`X`=Yes) — include for executables
+- `UCCHECK`: Unicode checks active (`X`=Yes)
+
+**Note**: The serializer may also write a `<TPOOL>` section after `<PROGDIR>` if the program has a title text. You do not need to write this when creating new programs — abapGit will add it on the next pull if needed.
 
 ---
 
@@ -149,8 +248,10 @@ abapGit needs XML files to:
 
 **Filename**: `src/zmy_table.tabl.xml`
 
+> **XML-only object** — no `.abap` source file. Pull with: `pull --files src/zmy_table.tabl.xml`
+
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_TABL" serializer_version="v1.0.0">
  <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
   <asx:values>
@@ -168,9 +269,20 @@ abapGit needs XML files to:
 
 **Key Fields**:
 - `TABNAME`: Table name
-- `DDTEXT`: Description (NOT DESCRIPT)
-- `TABCLASS`: Table class (TRANSP = Transparent)
-- `CONTFLAG`: Delivery class (A = Application table)
+- `DDTEXT`: Description (**not** `DESCRIPT`)
+- `TABCLASS`: `TRANSP`=Transparent (most common), `POOL`, `CLUSTER`
+- `CONTFLAG`: Delivery class — `A`=Application, `C`=Customizing, `S`=System, `G`=Customizing protected
+
+**Note**: When abapGit serializes an existing table it also writes `<DD09L>` (technical settings) and `<DD03P_TABLE>` (field definitions). These sections are generated automatically from the ABAP Dictionary on pull — you only need the `<DD02V>` header when creating a new table. After the first pull the XML will be expanded with those sections.
+
+**`DD03P` field-level rules** (apply when editing an existing table XML that includes `<DD03P_TABLE>`):
+
+| Rule | Detail |
+|---|---|
+| `SHLPORIGIN` | Include `<SHLPORIGIN>D</SHLPORIGIN>` on fields where the Dictionary provides a value help (e.g. fields with a domain that has fixed values or a search help). Omit on fields with no value help. |
+| Field order for raw-type fields | For fields with no `ROLLNAME` (raw type, e.g. `CHAR`, `NUMC`), the serializer writes `<MASK>` **before** `<DDTEXT>`. For fields with a `ROLLNAME`, only `ROLLNAME` appears (no `MASK` or `DDTEXT`). |
+
+**Why this matters**: Missing `SHLPORIGIN` or wrong `MASK`/`DDTEXT` order causes a permanent diff between git and the system-serialized XML.
 
 ---
 
@@ -181,7 +293,7 @@ abapGit needs XML files to:
 The XML format is identical for both types — only `SOURCE_TYPE` differs:
 
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_DDLS" serializer_version="v1.0.0">
  <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
   <asx:values>
@@ -207,8 +319,10 @@ The XML format is identical for both types — only `SOURCE_TYPE` differs:
 
 **Filename**: `src/zmy_dtel.dtel.xml`
 
+> **XML-only object** — no `.abap` source file. Pull with: `pull --files src/zmy_dtel.dtel.xml`
+
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
+<?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>
@@ -217,9 +331,9 @@ The XML format is identical for both types — only `SOURCE_TYPE` differs:
     <DDLANGUAGE>E</DDLANGUAGE>
     <DDTEXT>Description of data element</DDTEXT>
     <REPTEXT>Description</REPTEXT>
-    <SCRTEXT_S>Short</SCRTEXT_S>
-    <SCRTEXT_M>Medium</SCRTEXT_M>
-    <SCRTEXT_L>Long Description</SCRTEXT_L>
+    <SCRTEXT_S>Short text</SCRTEXT_S>
+    <SCRTEXT_M>Medium text</SCRTEXT_M>
+    <SCRTEXT_L>Long description text</SCRTEXT_L>
     <DTELMASTER>E</DTELMASTER>
     <DATATYPE>CHAR</DATATYPE>
     <LENG>000010</LENG>
@@ -231,9 +345,84 @@ The XML format is identical for both types — only `SOURCE_TYPE` differs:
 
 **Key Fields**:
 - `ROLLNAME`: Data element name
-- `DDTEXT`: Description (NOT DESCRIPT)
-- `DATATYPE`: Data type (CHAR, NUMC, etc.)
-- `LENG`: Length (e.g., 000010 for 10 characters)
+- `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)
+
+**Omit `<PARAMID>`** unless you specifically need a SET/GET parameter ID — the serializer omits it when empty, so including an empty tag causes a permanent diff.
+
+---
+
+### Structure (STRU)
+
+**Filename**: `src/zmy_struct.stru.xml`
+
+> **XML-only object** — no `.abap` source file. abapGit uses the same TABL serializer for STRU.
+> Pull with: `pull --files src/zmy_struct.stru.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_TABL" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <DD02V>
+    <TABNAME>ZMY_STRUCT</TABNAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <TABCLASS>INTTAB</TABCLASS>
+    <DDTEXT>Description of the structure</DDTEXT>
+    <CONTFLAG>A</CONTFLAG>
+   </DD02V>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key difference from TABL**: `TABCLASS` is `INTTAB` (internal table / structure) instead of `TRANSP`.
+
+**Note**: Like TABL, after the first pull abapGit expands the XML with `<DD03P_TABLE>` field definitions. When creating a new structure you only need the `<DD02V>` header.
+
+---
+
+### Table Type (TTYP)
+
+**Filename**: `src/zmy_ttyp.ttyp.xml`
+
+> **XML-only object** — no `.abap` source file.
+> Pull with: `pull --files src/zmy_ttyp.ttyp.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_TTYP" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <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>
+    <ACCESSMODE>T</ACCESSMODE>
+    <KEYDEF>D</KEYDEF>
+    <KEYKIND>N</KEYKIND>
+   </DD40V>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key Fields**:
+- `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
+- `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
+
+**Note**: After the first pull abapGit may expand the XML with `<DD42V>` (component definitions) if key fields are explicitly defined.
 
 ---
 

package/abap/guidelines/object-creation.md

@@ -12,14 +12,23 @@ grand_parent: ABAP Development
 
 **Each ABAP object requires an XML metadata file for abapGit to understand how to handle it.**
 
-| Object Type | ABAP File (if folder=/src/) | XML File | Details |
-|-------------|------------------------------|----------|---------|
-| Class | `src/zcl_*.clas.abap` | `src/zcl_*.clas.xml` | See `guidelines/abapgit.md` |
-| Interface | `src/zif_*.intf.abap` | `src/zif_*.intf.xml` | See `guidelines/abapgit.md` |
-| Program | `src/z*.prog.abap` | `src/z*.prog.xml` | See `guidelines/abapgit.md` |
-| Table | `src/z*.tabl.abap` | `src/z*.tabl.xml` | See `guidelines/abapgit.md` |
-| **CDS View Entity** | `src/zc_*.ddls.asddls` | `src/zc_*.ddls.xml` | **Use by default** - See `guidelines/cds.md` |
-| CDS View (legacy) | `src/zc_*.ddls.asddls` | `src/zc_*.ddls.xml` | Only if explicitly requested - See `guidelines/cds.md` |
+Replace `<name>` with the actual object name from this project's naming conventions
+(`guidelines/objects.local.md`, or `guidelines/objects.md` as fallback).
+
+| 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.
+> 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.**
 
@@ -37,14 +46,14 @@ When a class needs local helper classes or test doubles, use separate files:
 
 | File | Purpose |
 |------|---------|
-| `zcl_xxx.clas.locals_def.abap` | Local class definitions |
-| `zcl_xxx.clas.locals_imp.abap` | Local class implementations |
+| `<name>.clas.locals_def.abap` | Local class definitions |
+| `<name>.clas.locals_imp.abap` | Local class implementations |
 
 **XML Configuration**: Add `<CLSCCINCL>X</CLSCCINCL>` to the class XML to include local class definitions:
 
 ```xml
 <VSEOCLASS>
-  <CLSNAME>ZCL_XXX</CLSNAME>
+  <CLSNAME>MY_CLASS_NAME</CLSNAME>
   ...
   <CLSCCINCL>X</CLSCCINCL>
 </VSEOCLASS>

package/abap/guidelines/objects.md

@@ -8,67 +8,78 @@ grand_parent: ABAP Development
 
 # ABAP Object Naming Conventions
 
-> **Project-specific overrides**: Add your naming conventions to `guidelines/objects.local.md`.
-> That file is never overwritten by `abapgit-agent init --update` and is searched by the `ref` command.
+**Searchable keywords**: naming convention, prefix, namespace, object type, CLAS, INTF, PROG, TABL, DDLS, SAP namespace, customer namespace, PoC, probe
 
-**Searchable keywords**: naming convention, Z prefix, namespace, object type, CLAS, INTF, PROG, TABL, DDLS
+## SAP Namespace vs Customer Namespace
 
-## TOPICS IN THIS FILE
-1. Naming Conventions
-2. ABAP Object Types
-3. XML Metadata (see guidelines/abapgit.md)
+| | SAP Namespace | Customer Namespace |
+|---|---|---|
+| **Object prefix** | `CL_*`, `IF_*`, `/NAME/CL_*`, `/NAME/IF_*`, etc. | `Z*`, `Y*` |
+| **Package prefix** | SAP-delivered (e.g. `SFIN`, `CA_*`, `/NAME/*`) | `Z*`, `Y*`, `$*` |
+| **Ownership** | Delivered and maintained by SAP | Owned by the customer |
+| **In git repo** | Objects from an SAP-delivered package | Custom development objects |
 
-## Naming Conventions
+> **Rule**: Never add customer-created objects (including PoC/probe classes) into SAP namespace
+> packages. PoC objects always use `Z*`/`Y*` prefix and always go in a `Z*`, `Y*`, or `$*` package
+> — even on a project where production objects use SAP namespace.
 
-Use `Z_` or `Y_` prefix for custom objects:
+## How to Determine This Project's Naming Convention
 
-| Object Type | Prefix | Example |
-|-------------|--------|---------|
-| Class | ZCL_ | ZCL_MY_CLASS |
-| Interface | ZIF_ | ZIF_MY_INTERFACE |
-| Program | Z | ZMY_PROGRAM |
-| Package | $ | $MY_PACKAGE |
-| Table | Z | ZMY_TABLE |
-| CDS View | ZC | ZC_MY_VIEW |
-| CDS Entity | ZE | ZE_MY_ENTITY |
-| Data Element | Z | ZMY_ELEMENT |
-| Structure | Z | ZMY_STRUCTURE |
-| Table Type | Z | ZMY_TABLE_TYPE |
+```
+1. Check guidelines/objects.local.md  ← this project's actual conventions (always check first)
+2. No objects.local.md exists?        ← assume customer namespace project, use Z/Y defaults below
+```
 
-## ABAP Object Types
+`objects.local.md` is never overwritten by `abapgit-agent init --update`. It specifies the
+naming pattern for production objects in this project — which could be customer namespace
+(`ZCL_*`, `YCL_*`) or SAP namespace (`CL_*`, `/NAMESPACE/CL_*`).
 
-Common object types in this project:
+## Default Naming Conventions (Z/Y customer namespace)
 
-| Type | Description | File Suffix |
-|------|-------------|-------------|
-| CLAS | Classes | .clas.abap |
-| PROG | Programs | .prog.abap |
-| FUGR | Function Groups | .fugr.abap |
-| INTF | Interfaces | .intf.abap |
-| TABL | Tables | .tabl.abap |
-| STRU | Structures | .stru.abap |
-| DTEL | Data Elements | .dtel.abap |
-| TTYP | Table Types | .ttyp.abap |
-| DDLS | CDS Views | .ddls.asddls |
-| DDLX | CDS Entities | .ddlx.asddlx |
+Applied when no `objects.local.md` exists:
 
-## XML Metadata
+| Object Type | Default Prefix | Default Example |
+|-------------|---------------|-----------------|
+| Class | `ZCL_` | `ZCL_MY_CLASS` |
+| Interface | `ZIF_` | `ZIF_MY_INTERFACE` |
+| Program | `Z` | `ZMY_PROGRAM` |
+| Package | `$` | `$MY_PACKAGE` |
+| Table | `Z` | `ZMY_TABLE` |
+| CDS View Entity | `ZC_` | `ZC_MY_VIEW` |
+| Data Element | `Z` | `ZMY_ELEMENT` |
+| Structure | `Z` | `ZMY_STRUCTURE` |
+| Table Type | `Z` | `ZMY_TABLE_TYPE` |
 
-**See guidelines/abapgit.md for XML templates.**
+## Project-Specific Conventions (`objects.local.md`)
 
-Each ABAP object requires an XML metadata file for abapGit. Quick reference:
+`objects.local.md` should define both the naming prefix **and the correct package(s)** for
+new objects. When package rules are present, Claude uses them directly without asking. When
+absent, Claude must ask the user which package to use.
+
+Examples of what `objects.local.md` might contain:
 
 ```
-Class:         zcl_*.clas.xml
-Interface:     zif_*.intf.xml
-Table:         z*.tabl.xml
-CDS View:      zc_*.ddls.xml
-```
+# Customer namespace — Y prefix
+Class prefix:     YCL_    e.g. YCL_MY_CLASS
+Interface prefix: YIF_    e.g. YIF_MY_INTERFACE
+Default package:  YMYPROJECT
 
-**Important**: Always push to git BEFORE running pull:
-```bash
-git add .
-git commit -m "Changes"
-git push           # CRITICAL: Push FIRST
-abapgit-agent pull --files abap/zcl_my_class.clas.abap
+# SAP namespace project — single package
+Class prefix:     CL_     e.g. CL_MY_CLASS
+Interface prefix: IF_     e.g. IF_MY_INTERFACE
+Default package:  MY_PACKAGE
+
+# SAP namespace project — multiple packages
+Class prefix:     CL_     e.g. CL_MY_CLASS
+Interface prefix: IF_     e.g. IF_MY_INTERFACE
+Packages:
+  - Feature A objects → MY_PACKAGE_A
+  - Feature B objects → MY_PACKAGE_B
+
+# SAP registered namespace
+Class prefix:     /MYNAMESPACE/CL_
+Default package:  /MYNAMESPACE/MAIN
 ```
+
+→ For file structure (what files to create): `abapgit-agent ref --topic object-creation`
+→ For XML templates: `abapgit-agent ref --topic abapgit`

package/abap/guidelines/probe-poc.md

@@ -0,0 +1,146 @@
+---
+layout: default
+title: Probe and PoC Guide
+nav_order: 19
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
+# Probe and PoC — Full Decision Flow
+
+**Searchable keywords**: probe, PoC, proof of concept, scratchWorkspace, pocWorkspace,
+disableProbeClasses, SAP namespace, customer namespace, throwaway class
+
+## Probe vs PoC — Key Difference
+
+| | Probe | PoC |
+|---|---|---|
+| Intent | Throwaway — run once to test something | Validate an idea — may persist, needs proper home |
+| Naming | Auto-derived (`ZCL_{USER}_*`) | Developer chooses a meaningful name |
+| Location | `scratchWorkspace` (separate repo) | `pocWorkspace` (separate repo, manually set up) |
+| Config | `scratchWorkspace` in `.abapGitAgent` | `pocWorkspace` in `.abapGitAgent` |
+
+Both always use `Z*`/`Y*` prefix and a customer namespace package (`Z*`, `Y*`, `$*`).
+Never use SAP namespace prefix or SAP-delivered package for probe/PoC objects.
+
+---
+
+## How to Determine the Project Namespace
+
+Before applying the decision flow, determine the project namespace from `objects.local.md`:
+
+```
+objects.local.md shows Z*/Y* prefix  OR  no objects.local.md exists
+  → Customer namespace project
+
+objects.local.md shows CL_*, IF_*, /NAMESPACE/* prefix
+  → SAP namespace project
+```
+
+---
+
+## Full Decision Flow
+
+```
+User asks to create an object
+│
+├── SAP namespace project AND user provides a Z*/Y* name
+│   └── Ask: "Production objects here use CL_* prefix. Did you mean CL_MY_HELPER?
+│           Or is this a PoC/probe object?"
+│       ├── "PoC/probe"   →  continue as PoC or probe flow below
+│       └── "Production"  →  correct the name to match project prefix, then proceed
+│
+├── User confirms PROBE
+│   ├── Customer namespace project
+│   │   ├── disableProbeClasses = false / not set
+│   │   │   └── Create in current project (Z*/Y* prefix, Z*/Y*/$* package)
+│   │   └── disableProbeClasses = true
+│   │       ├── scratchWorkspace configured  →  create there (see workflow below)
+│   │       └── scratchWorkspace NOT configured
+│   │           └── STOP — tell user to configure scratchWorkspace in .abapGitAgent
+│   │
+│   └── SAP namespace project
+│       ├── scratchWorkspace configured  →  create there (see workflow below)
+│       └── scratchWorkspace NOT configured
+│           └── STOP — tell user to configure scratchWorkspace in .abapGitAgent
+│           (disableProbeClasses is irrelevant for SAP namespace projects —
+│            they have no customer namespace packages to host probes)
+│
+└── User confirms POC
+    ├── pocWorkspace.path configured in .abapGitAgent
+    │   └── Read {pocWorkspace.path}/.abapGitAgent → get package property
+    │       Show confirmation:
+    │         "I'll create this PoC object in:
+    │            Repo:    {pocWorkspace.path}
+    │            Package: {package from that repo's .abapGitAgent}
+    │          Is this correct, or do you want a different PoC repo?"
+    │       ├── Confirmed        →  work in that repo using its naming/package rules
+    │       └── Different repo   →  ask user for the path, then confirm again
+    └── pocWorkspace.path NOT configured
+        └── STOP — tell user to set up a PoC repo first (see setup below)
+```
+
+---
+
+## Probe Workflow (scratchWorkspace)
+
+**Naming** — derive from `scratchWorkspace` config in `.abapGitAgent`:
+- `classPrefix` (default: `ZCL_{USER}_`) + `<PURPOSE>`, max 30 chars
+- Example: user=`JOHN`, purpose=`OPEN_TRANSPORTS` → `ZCL_JOHN_OPEN_TRANSPORTS`
+- If name already exists in `{path}/src/`, append `_2`, `_3`, etc.
+
+**Workflow:**
+1. Read `{scratchWorkspace.path}/.abapGitAgent` to confirm `folder` property (e.g. `/src/`)
+2. Write class files in `{path}/src/`
+3. Commit and push from `{path}`:
+   ```bash
+   cd {path} && git add . && git commit -m "probe: <description>" && git push
+   ```
+4. Activate:
+   ```bash
+   cd {path} && abapgit-agent pull --files src/<classname>.clas.abap
+   ```
+5. Tell user (do NOT auto-run):
+   ```
+   Class activated. Run with: abapgit-agent run --class <CLASSNAME>
+   ```
+   Run the command from the original project directory, not `{path}`.
+
+---
+
+## PoC Workflow (pocWorkspace)
+
+Once the user confirms the repo and package:
+
+1. Read `{pocWorkspace.path}/.abapGitAgent` → get `folder` and `package`
+2. Read `{pocWorkspace.path}/guidelines/objects.local.md` if it exists → use its naming rules
+3. Write object files in `{pocWorkspace.path}/{folder}/`
+4. Commit and push from `{pocWorkspace.path}`:
+   ```bash
+   cd {pocWorkspace.path} && git add . && git commit -m "poc: <description>" && git push
+   ```
+5. Activate:
+   ```bash
+   cd {pocWorkspace.path} && abapgit-agent pull --files {folder}/<name>.<ext> --sync-xml
+   ```
+
+---
+
+## PoC Repo Setup (one-time, manual)
+
+When `pocWorkspace.path` is not configured, tell the user to:
+
+```
+1. Create a git repo for the PoC:
+     mkdir my-poc && cd my-poc && git init && git remote add origin <url>
+
+2. Link it to an ABAP package:
+     abapgit-agent init --package <POC_PACKAGE>
+
+3. Add pocWorkspace to .abapGitAgent in the main project:
+     "pocWorkspace": { "path": "/absolute/path/to/my-poc" }
+```
+
+**Switching PoCs**: update `pocWorkspace.path` to point to the new PoC repo.
+Claude always shows the current repo and package before creating anything —
+a stale path is caught before any files are written.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.13.2",
+  "version": "1.13.4",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "files": [
     "bin/",
@@ -27,6 +27,8 @@
     "test:cmd:demo": "node tests/run-all.js --cmd --demo",
     "test:cmd:syntax": "node tests/run-all.js --cmd --command=syntax",
     "test:cmd:pull": "node tests/run-all.js --cmd --command=pull",
+    "test:sync-xml": "node tests/run-all.js --sync-xml",
+    "test:xml-only": "node tests/run-all.js --xml-only",
     "test:cmd:inspect": "node tests/run-all.js --cmd --command=inspect",
     "test:cmd:unit": "node tests/run-all.js --cmd --command=unit",
     "test:cmd:view": "node tests/run-all.js --cmd --command=view",

package/src/commands/pull.js

@@ -5,6 +5,7 @@
 const { printHttpError } = require('../utils/format-error');
 const fs = require('fs');
 const pathModule = require('path');
+const { execSync } = require('child_process');
 
 // Calculate display width accounting for emoji (2 cells) vs ASCII (1 cell)
 function calcWidth(str) {
@@ -42,6 +43,7 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp, gitUtils, getTransport, getSafeguards, getConflictSettings, getTransportSettings } = context;
     const verbose = args.includes('--verbose');
+    const syncXml = args.includes('--sync-xml');
 
     // Check project-level safeguards
     const safeguards = getSafeguards();
@@ -96,21 +98,31 @@ module.exports = {
     if (filesArgIndex !== -1 && filesArgIndex + 1 < args.length) {
       files = args[filesArgIndex + 1].split(',').map(f => f.trim());
 
-      // Validate that every file has a recognised ABAP source extension
-      // (.abap or .asddls) — XML metadata files must NOT be passed here
+      // Validate that every file has a recognised extension:
+      // - .abap / .asddls  — ABAP source files
+      // - name.type.xml    — XML-only objects (TABL, STRU, DTEL, TTYP, ...)
+      //   Must have exactly 3 dot-separated parts with a non-empty name part
+      //   to exclude .abapgit.xml, package.devc.xml, plain .xml, etc.
       const ABAP_SOURCE_EXTS = new Set(['abap', 'asddls']);
+      const isXmlOnlyObject = (f) => {
+        const base = f.split('/').pop();
+        const parts = base.split('.');
+        return parts.length === 3 && parts[0].length > 0 && parts[2].toLowerCase() === 'xml';
+      };
       const nonSourceFiles = files.filter(f => {
         const base = f.split('/').pop(); // strip directory
         const parts = base.split('.');
         const ext = parts[parts.length - 1].toLowerCase();
-        return parts.length < 3 || !ABAP_SOURCE_EXTS.has(ext);
+        if (ABAP_SOURCE_EXTS.has(ext)) return false;  // .abap / .asddls — valid
+        if (isXmlOnlyObject(f)) return false;          // name.type.xml — valid
+        return true;                                   // everything else — invalid
       });
       if (nonSourceFiles.length > 0) {
-        console.error('❌ Error: --files only accepts ABAP source files (.abap, .asddls).');
-        console.error('   The following file(s) are not ABAP source files:');
+        console.error('❌ Error: --files only accepts ABAP source files (.abap, .asddls) or XML-only object files (name.type.xml).');
+        console.error('   The following file(s) are not recognised:');
         nonSourceFiles.forEach(f => console.error(`     ${f}`));
-        console.error('   Tip: pass the source file, not the XML metadata file.');
-        console.error('   Example: --files src/zcl_my_class.clas.abap');
+        console.error('   Tip: for source objects pass the .abap file; for XML-only objects (TABL, STRU, DTEL, TTYP)');
+        console.error('   pass the .xml file, e.g. --files abap/ztable.tabl.xml');
         process.exit(1);
       }
 
@@ -198,13 +210,13 @@ module.exports = {
       }
     }
 
-    await this.pull(gitUrl, branch, files, transportRequest, loadConfig, AbapHttp, jsonOutput, undefined, conflictMode, verbose);
+    await this.pull(gitUrl, branch, files, transportRequest, loadConfig, AbapHttp, jsonOutput, undefined, conflictMode, verbose, syncXml);
   },
 
-  async pull(gitUrl, branch = 'main', files = null, transportRequest = null, loadConfig, AbapHttp, jsonOutput = false, gitCredentials = undefined, conflictMode = 'abort', verbose = false) {
+  async pull(gitUrl, branch = 'main', files = null, transportRequest = null, loadConfig, AbapHttp, jsonOutput = false, gitCredentials = undefined, conflictMode = 'abort', verbose = false, syncXml = false, isRepull = false) {
     const TERM_WIDTH = process.stdout.columns || 80;
 
-    if (!jsonOutput) {
+    if (!jsonOutput && !isRepull) {
       console.log(`\n🚀 Starting pull for: ${gitUrl}`);
       console.log(`   Branch: ${branch}`);
       if (files && files.length > 0) {
@@ -438,6 +450,71 @@ module.exports = {
         throw err;
       }
 
+      // --- Post-pull XML sync ---
+      // abapGit's status calculation already identified which XML files differ
+      // (match=false) — only those are returned in local_xml_files.
+      const localXmlFiles = result.local_xml_files || result.LOCAL_XML_FILES || [];
+
+      if (localXmlFiles.length > 0) {
+        const diffFiles = [];
+        for (const f of localXmlFiles) {
+          const relPath = ((f.path || f.PATH || '') + (f.filename || f.FILENAME || '')).replace(/^\//, '');
+          const absPath = pathModule.join(process.cwd(), relPath);
+          if (!fs.existsSync(absPath)) continue;
+          const incoming = Buffer.from(f.data || f.DATA, 'base64');
+          // Double-check: only write if bytes actually differ (guard against encoding quirks)
+          const current = fs.readFileSync(absPath);
+          if (!current.equals(incoming)) {
+            diffFiles.push({ relPath, absPath, incoming });
+          }
+        }
+
+        if (diffFiles.length > 0 && !syncXml) {
+          console.log(`\n⚠️  ${diffFiles.length} XML file(s) differ from serializer output:`);
+          for (const f of diffFiles) console.log(`   ${f.relPath}`);
+          console.log(`   Run with --sync-xml to accept serializer output and amend the last commit`);
+        } else if (diffFiles.length > 0 && syncXml) {
+          console.log(`\n🔄 Syncing ${diffFiles.length} XML file(s) to match serializer output:`);
+          for (const f of diffFiles) console.log(`   ${f.relPath}`);
+
+          // 1. Write serializer XML to disk
+          for (const f of diffFiles) fs.writeFileSync(f.absPath, f.incoming);
+
+          // 2. Stage changed XML files
+          const quotedPaths = diffFiles.map(f => `"${f.relPath}"`).join(' ');
+          execSync(`git add ${quotedPaths}`, { cwd: process.cwd() });
+
+          // 3. Amend last commit
+          execSync('git commit --amend --no-edit', { cwd: process.cwd() });
+
+          // 4. Push with force-with-lease; if no upstream, set it automatically
+          let pushed = false;
+          try {
+            execSync('git push --force-with-lease', { cwd: process.cwd(), stdio: 'pipe' });
+            pushed = true;
+          } catch (pushErr) {
+            const msg = (pushErr.stderr || pushErr.stdout || pushErr.message || '').toString();
+            if (msg.includes('no upstream branch') || msg.includes('has no upstream')) {
+              // Branch not yet pushed — set upstream and force push (amend requires force)
+              execSync(`git push --force-with-lease --set-upstream origin ${branch}`, { cwd: process.cwd(), stdio: 'pipe' });
+              pushed = true;
+            }
+            // Any other push error (no remote at all, auth failure, etc.) → skip silently
+          }
+
+          if (pushed) {
+            console.log(`   Re-pulling so ABAP system matches the amended commit...`);
+            // 5. Re-pull so ABAP system matches the amended commit (no sync loop)
+            await this.pull(gitUrl, branch, files, transportRequest, loadConfig, AbapHttp, jsonOutput, gitCredentials, conflictMode, verbose, false, true);
+            console.log(`\n✅ Synced ${diffFiles.length} XML file(s), amended commit, re-pulled`);
+          } else {
+            // No remote at all — files are written and committed locally
+            console.log(`\n✅ Synced ${diffFiles.length} XML file(s), amended commit`);
+            console.log(`   Push skipped (no remote). Push manually to sync with remote.`);
+          }
+        }
+      }
+
       return result;
     } catch (error) {
       if (error._isPullError) {