abapgit-agent 1.12.0 → 1.13.0

package/README.md

@@ -49,138 +49,49 @@ See [Creating New ABAP Projects](INSTALL.md#creating-new-abap-projects) to set u
 
 ## CLI Commands
 
-### Setup Commands
+### Setup
 
 ```bash
-# Initialize local configuration for existing git repo
-abapgit-agent init --package ZMY_PACKAGE
-
-# With custom folder (default: /src/)
-abapgit-agent init --package ZMY_PACKAGE --folder /abap/
-
-# With custom folder logic (default: PREFIX)
-abapgit-agent init --package ZMY_PACKAGE --folder-logic FULL
-
-# Create online repository in ABAP
-abapgit-agent create
-
-# Delete online repository from ABAP (keeps local files)
-abapgit-agent delete
-
-# Import objects from ABAP package to git
-abapgit-agent import
-```
-
-### Development Commands
-
-```bash
-# Pull and activate (auto-detects git remote and branch)
-abapgit-agent pull
-
-# Pull with specific branch
-abapgit-agent pull --branch develop
-
-# Pull specific files only (fast iteration)
-abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zif_my_intf.intf.abap
-
-# Override git URL if needed
-abapgit-agent pull --url https://github.com/user/repo --branch main
-
-# Pull with a specific transport request
-abapgit-agent pull --transport DEVK900001
-
-# Import objects from ABAP package to git
-abapgit-agent import
-
-# Import with custom commit message
-abapgit-agent import --message "feat: add new feature"
+abapgit-agent init --package ZMY_PACKAGE   # Initialize local config
+abapgit-agent create                        # Create online repo in ABAP
+abapgit-agent import                        # Import objects from ABAP to git
+abapgit-agent delete                        # Delete repo from ABAP
 ```
 
-### Validation Commands
+### Development
 
 ```bash
-# Check syntax of local source files BEFORE commit (fast, no activation)
-# Supported: CLAS, INTF, PROG, DDLS (CDS Views)
-abapgit-agent syntax --files src/zcl_my_class.clas.abap
-abapgit-agent syntax --files src/zc_my_view.ddls.asddls
-
-# Syntax check with ABAP Cloud mode
-abapgit-agent syntax --files src/zcl_my_class.clas.abap --cloud
-
-# Syntax check multiple files
-abapgit-agent syntax --files src/zcl_class.clas.abap,src/zc_view.ddls.asddls
-
-# Inspect source file for issues (after activation)
-abapgit-agent inspect --files src/zcl_my_class.clas.abap
-
-# Run AUnit tests for test classes
-abapgit-agent unit --files src/zcl_my_test.clas.testclasses.abap
-
-# Run tests for multiple test classes
-abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.clas.testclasses.abap
+abapgit-agent pull                                         # Pull and activate
+abapgit-agent pull --files src/zcl_my_class.clas.abap     # Pull specific files
+abapgit-agent syntax --files src/zcl_my_class.clas.abap   # Check syntax before commit
+abapgit-agent inspect --files src/zcl_my_class.clas.abap  # Code Inspector after pull
+abapgit-agent unit --files src/zcl_my_test.clas.testclasses.abap  # Run AUnit tests
+abapgit-agent run --class ZCL_MY_RUNNER                   # Execute class headlessly
 ```
 
-### Explore Commands
+### Explore
 
 ```bash
-# Display package hierarchy tree
-abapgit-agent tree --package '$MY_PACKAGE'
-
-# View object definitions from ABAP system (classes, interfaces, tables, data elements)
-abapgit-agent view --objects ZCL_MY_CLASS
-abapgit-agent view --objects SFLIGHT --type TABL
-abapgit-agent view --objects S_CARR_ID --type DTEL
-
-# Preview table or CDS view data
-abapgit-agent preview --objects SFLIGHT
-abapgit-agent preview --objects ZC_MY_CDS_VIEW --type DDLS
-abapgit-agent preview --objects SFLIGHT --limit 20
-abapgit-agent preview --objects SFLIGHT --where "CARRID = 'AA'"
-abapgit-agent preview --objects SFLIGHT --columns CARRID,CONNID,PRICE
-abapgit-agent preview --objects SFLIGHT --vertical
-abapgit-agent preview --objects SFLIGHT --compact
-
-# Find where-used (objects using a specific object)
-abapgit-agent where --objects ZCL_MY_CLASS
-abapgit-agent where --objects ZIF_MY_INTERFACE
-abapgit-agent where --objects ZCL_MY_CLASS --type CLAS
-
-# Query short dumps (ST22)
-abapgit-agent dump --date TODAY
-abapgit-agent dump --user DEVELOPER --date TODAY --detail 1
+abapgit-agent tree --package '$MY_PACKAGE'   # Package hierarchy
+abapgit-agent list --package '$MY_PACKAGE'   # List objects
+abapgit-agent view --objects ZCL_MY_CLASS    # View object definition
+abapgit-agent preview --objects SFLIGHT      # Preview table data
+abapgit-agent where --objects ZCL_MY_CLASS   # Where-used list
+abapgit-agent dump --date TODAY              # Query short dumps (ST22)
+abapgit-agent debug set --files abap/zcl_my_class.clas.abap:42  # Set breakpoint
 ```
 
-### Debug Commands
+### Utility
 
 ```bash
-# Set a breakpoint
-abapgit-agent debug set --files abap/zcl_my_class.clas.abap:42
-
-# Attach and debug interactively (human REPL)
-abapgit-agent debug attach
-
-# Attach in scripted AI mode — emits JSON on hit, starts background daemon
-abapgit-agent debug attach --json
-
-# Step, inspect variables, call stack (no --session needed)
-abapgit-agent debug step --type over --json
-abapgit-agent debug vars --json
-abapgit-agent debug stack --json
-
-# Always release the frozen work process when done
-abapgit-agent debug step --type continue --json
-```
-
-### Utility Commands
-
-```bash
-# Health check
-abapgit-agent health
-
-# Check integration status
-abapgit-agent status
+abapgit-agent guide                   # Read full ABAP development guide
+abapgit-agent ref "CORRESPONDING"     # Search ABAP reference
+abapgit-agent ref --topic sql         # Browse by topic
+abapgit-agent transport list          # List transport requests
+abapgit-agent upgrade                 # Upgrade CLI and ABAP backend
+abapgit-agent status                  # Check configuration
+abapgit-agent health                  # Verify ABAP connection
 ```
-Note: All ABAP commands automatically check CLI/ABAP API version compatibility.
 
 ## Local Development
 
@@ -200,25 +111,11 @@ npm run pull -- --url <git-url> --branch main
 
 | Topic | File |
 |-------|------|
+| Full Documentation | [https://sylvoscai.github.io/abapgit-agent/](https://sylvoscai.github.io/abapgit-agent/) |
 | Installation & Setup | [INSTALL.md](INSTALL.md) |
-| init Command | [docs/init-command.md](docs/init-command.md) |
-| create Command | [docs/create-command.md](docs/create-command.md) |
-| delete Command | [docs/delete-command.md](docs/delete-command.md) |
-| import Command | [docs/import-command.md](docs/import-command.md) |
-| pull Command | [docs/pull-command.md](docs/pull-command.md) |
-| syntax Command | [docs/syntax-command.md](docs/syntax-command.md) |
-| inspect Command | [docs/inspect-command.md](docs/inspect-command.md) |
-| unit Command | [docs/unit-command.md](docs/unit-command.md) |
-| tree Command | [docs/tree-command.md](docs/tree-command.md) |
-| view Command | [docs/view-command.md](docs/view-command.md) |
-| preview Command | [docs/preview-command.md](docs/preview-command.md) |
-| where Command | [docs/where-command.md](docs/where-command.md) |
-| dump Command | [docs/dump-command.md](docs/dump-command.md) |
-| debug Command | [docs/debug-command.md](docs/debug-command.md) |
-| ref Command | [docs/ref-command.md](docs/ref-command.md) |
+| All Commands Overview | [docs/commands.md](docs/commands.md) |
 | REST API Reference | [API.md](API.md) |
 | Error Handling | [ERROR_HANDLING.md](ERROR_HANDLING.md) |
-| ABAP Coding Guidelines | [abap/CLAUDE.md](abap/CLAUDE.md) |
 
 ## Dependent Projects
 

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

@@ -0,0 +1,114 @@
+# ABAP Development with abapGit
+
+You are working on an ABAP project using abapGit for version control.
+
+> **Full guide:** https://sylvoscai.github.io/abapgit-agent/pages/abap-coding-guidelines.html
+> **Agent mode:** Run `abapgit-agent guide` for the complete guide with all rules.
+
+---
+
+## Critical Rules
+
+### 1. Use `ref` Command for Unfamiliar Topics
+
+**When starting to work on ANY unfamiliar ABAP topic, syntax, or pattern, use the `ref` command BEFORE writing any code.**
+
+```bash
+abapgit-agent ref "CORRESPONDING"          # search by pattern
+abapgit-agent ref --topic exceptions       # browse by topic
+abapgit-agent ref --topic debug-session    # read full guideline file
+abapgit-agent ref --topic workflow-detailed
+```
+
+### 2. Read `.abapGitAgent` for Folder Location and Naming Conventions
+
+**Before creating ANY ABAP object file, read `.abapGitAgent` to determine the correct folder.**
+
+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`)
+
+**Check naming conventions before creating any new object:**
+1. `guidelines/objects.local.md` ← project-specific overrides (if file exists)
+2. `abapgit-agent ref --topic objects` ← default Z/Y prefix conventions
+
+### 3. Create XML Metadata / Local Classes
+
+Each ABAP object needs an XML metadata file. Local helper/test-double classes use separate `.locals_def.abap` / `.locals_imp.abap` files.
+
+```bash
+abapgit-agent ref --topic object-creation   # XML templates and local class setup
+```
+
+### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG, DDLS)
+
+```bash
+abapgit-agent syntax --files src/zcl_my_class.clas.abap
+```
+
+For dependent files (interface + class), skip `syntax` and go straight to `pull`.
+
+### 5. Use `ref`, `view` and `where` to Learn About Unknown Classes/Methods
+
+```bash
+abapgit-agent where --objects ZIF_UNKNOWN_INTERFACE
+abapgit-agent view --objects ZCL_UNKNOWN_CLASS
+abapgit-agent view --objects ZCL_UNKNOWN_CLASS --full --lines   # with line numbers for debugging
+```
+
+### 6. Troubleshooting
+
+```bash
+abapgit-agent dump --date TODAY --detail 1    # inspect last crash (ST22)
+abapgit-agent debug set --objects ZCL_FOO:42  # set breakpoint then attach
+abapgit-agent ref --topic debug-session       # full debug guide
+abapgit-agent ref --topic debug-dump          # dump analysis guide
+```
+
+---
+
+## Development Workflow
+
+### Project-Level Config (`.abapgit-agent.json`)
+
+Checked into the repository — applies to all developers. **Read this file at the start of every session.**
+
+| Setting | Effect |
+|---------|--------|
+| `safeguards.requireFilesForPull: true` | Always include `--files` in every `pull` |
+| `safeguards.disablePull: true` | Do not run `abapgit-agent pull` at all |
+| `conflictDetection.mode: "abort"` | Abort pull on conflict — inform user |
+| `transports.allowCreate/allowRelease: false` | Blocked — inform user |
+
+### Workflow Mode (`.abapGitAgent` → `workflow.mode`)
+
+| Mode | Branch Strategy | Rebase Before Pull | Create PR |
+|------|----------------|-------------------|-----------|
+| `"branch"` | Feature branches | ✓ Always | ✓ Yes (squash merge) |
+| `"trunk"` / not set | Direct to default branch | ✗ No | ✗ No |
+
+```bash
+# branch mode — read full guide:
+abapgit-agent ref --topic branch-workflow
+```
+
+### Quick Decision Tree
+
+```
+Modified ABAP files?
+├─ CLAS/INTF/PROG/DDLS files?
+│  ├─ Independent files?  → syntax → commit → push → pull
+│  └─ Dependent files?    → skip syntax → commit → push → pull
+└─ Other types (FUGR, TABL, etc.)?
+   → skip syntax → commit → push → pull → (if errors: inspect)
+```
+
+```bash
+abapgit-agent ref --topic workflow-detailed   # full workflow decision tree
+```
+
+---
+
+## Project-Specific Naming Conventions
+
+See `guidelines/objects.local.md` for this project's naming convention overrides.

package/abap/CLAUDE.md

@@ -9,20 +9,26 @@ parent: ABAP Development
 
 This file provides guidelines for **generating ABAP code** in abapGit repositories.
 
-**Use this file as a template**: Copy it to your ABAP repository root when setting up new projects with Claude Code.
-
 ---
 
 ## Critical Rules
 
-### 1. Use `ref` Command for Unfamiliar Topics
+### 1. Use `guide` and `ref` Commands for Unfamiliar Topics
 
-**When starting to work on ANY unfamiliar ABAP topic, syntax, or pattern, you MUST use the `ref` command BEFORE writing any code.**
+**When starting a new session or working on ANY unfamiliar ABAP topic, syntax, or pattern:**
 
 ```
 ❌ WRONG: Start writing code immediately based on assumptions
-✅ CORRECT: Run ref command first to look up the correct pattern
+✅ CORRECT: Run guide first, then ref for specific topics
+```
+
+**Step 1 — Read the full dev guide at session start:**
+```bash
+abapgit-agent guide
 ```
+Covers the complete workflow, all critical rules, object naming, unit testing, debugging, and the full guidelines index.
+
+**Step 2 — Look up specific syntax or topics with ref:**
 
 **Why**: ABAP syntax is strict. Guessing leads to activation errors that waste time.
 
@@ -81,7 +87,7 @@ The folder is configured in `.abapGitAgent` (property: `folder`):
 ### 3. Create XML Metadata / Local Classes
 
 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` for XML templates and local class setup
+→ See `guidelines/object-creation.md` — run: `abapgit-agent ref --topic object-creation`
 
 ---
 
@@ -133,18 +139,19 @@ abapgit-agent pull --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
 
 ### 5. Local Helper / Test-Double Classes
 
-→ See `guidelines/object-creation.md` for local class setup (`locals_def.abap` / `locals_imp.abap`)
+→ See `guidelines/object-creation.md` — run: `abapgit-agent ref --topic object-creation`
 
 ---
 
-### 6. Use `ref`, `view` and `where` Commands to Learn About Unknown Classes/Methods
+### 6. Use `guide`, `ref`, `view` and `where` Commands to Learn About Unknown Classes/Methods
 
 **When working with unfamiliar ABAP classes or methods, follow this priority:**
 
 ```
 1. First: Check local git repo for usage examples
-2. Second: Check ABAP reference/cheat sheets
-3. Third: Use view/where commands to query ABAP system (if needed)
+2. Second: Run abapgit-agent guide for the full ABAP dev guide
+3. Third: Use ref for specific syntax/topic details
+4. Fourth: Use view/where commands to query ABAP system (if needed)
 ```
 
 #### Priority 1: Check Local Git Repository
@@ -154,7 +161,16 @@ abapgit-agent pull --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
 - Check how similar classes are implemented
 - This gives the most relevant context for your project
 
-#### Priority 2: Check ABAP References
+#### Priority 2: Read the ABAP Development Guide
+
+```bash
+# Read the full bundled ABAP dev guide (workflow, patterns, guidelines index)
+abapgit-agent guide
+```
+
+This covers the complete development workflow, coding guidelines, object naming, unit testing patterns, and debugging guide. Always up-to-date with the installed package version.
+
+#### Priority 3: Check ABAP References
 
 ```bash
 # Search in ABAP cheat sheets and guidelines
@@ -163,7 +179,7 @@ abapgit-agent ref "INTERFACE"
 abapgit-agent ref --topic classes
 ```
 
-#### Priority 3: Use `where` and `view` Commands (Query ABAP System)
+#### Priority 4: Use `where` and `view` Commands (Query ABAP System)
 
 **If local/references don't have the answer, query the ABAP system:**
 
@@ -180,6 +196,13 @@ abapgit-agent view --objects ZCL_UNKNOWN_CLASS
 
 # View specific METHOD implementation
 abapgit-agent view --objects ZCL_UNKNOWN_CLASS=============CM001
+
+# View FULL source (definition + all method implementations)
+abapgit-agent view --objects ZCL_UNKNOWN_CLASS --full
+
+# View FULL source with dual line numbers (for setting breakpoints)
+# G [N]  code — G = global line for debug set, [N] = include-relative
+abapgit-agent view --objects ZCL_UNKNOWN_CLASS --full --lines
 ```
 
 **Example workflow for AI:**
@@ -188,9 +211,9 @@ User: "How do I use ZCL_ABGAGT_AGENT?"
 
 AI thought process:
 1. Search local repo for ZCL_ABGAGT_AGENT usage
-2. Found: It's instantiated in several places with ->pull() method
-3. Still unclear about parameters? Check view command
-4. View: abapgit-agent view --objects ZCL_ABGAGT_AGENT
+2. Run: abapgit-agent guide  ← check if covered in the dev guide
+3. Run: abapgit-agent ref "ZCL_ABGAGT_AGENT"  ← search guidelines
+4. Still unclear? Run: abapgit-agent view --objects ZCL_ABGAGT_AGENT
 ```
 
 **Key differences:**
@@ -202,7 +225,7 @@ AI thought process:
 ### 7. CDS Unit Tests
 
 Use `CL_CDS_TEST_ENVIRONMENT` for unit tests that read CDS views.
-→ See `guidelines/cds-testing.md` for code examples
+→ See `guidelines/cds-testing.md` — run: `abapgit-agent ref --topic cds-testing`
 
 ---
 
@@ -237,7 +260,7 @@ After activating a class, stop and tell the user: `"Class is activated. Run with
 
 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.
 
-→ See `guidelines/run-probe-classes.md` for naming conventions, full workflow, and refusal guidance
+→ See `guidelines/run-probe-classes.md` — run: `abapgit-agent ref --topic run-probe-classes`
 
 ---
 
@@ -248,14 +271,43 @@ By default, probe/throwaway classes may be created in the current project. When
 | HTTP 500 / runtime crash (ST22) | `dump` | Error already occurred |
 | Wrong output, no crash | `debug` | Need to trace logic |
 
-Quick start:
+→ See `guidelines/debug-dump.md` — run: `abapgit-agent ref --topic debug-dump`
+
+**Critical rules for `debug` sessions:**
+
+1. **Always use `--json`** for all debug commands (`attach`, `vars`, `stack`, `step`) — human output is not machine-parseable
+2. **Attach BEFORE trigger** — start `debug attach --json` in background first, wait for `"Listener active"`, THEN fire the trigger (`unit`/`pull`/`run`)
+3. **Never pull to trigger** if a simpler trigger works — use `unit` when a test exists, `run` for a class runner; use `pull` only when the bug is specifically in the pull flow
+4. **Never pass `--session`** to `step/vars/stack` — it bypasses the daemon and causes errors
+5. **Always finish with `step --type continue --json`** — releases the frozen ABAP work process
+
+**Finding the right line number for a breakpoint:**
+
+Use `view --full --lines` to get assembled-source global line numbers (the `G` column) — these are the coordinates ADT accepts for breakpoints:
+
+```bash
+abapgit-agent view --objects ZCL_FOO --full --lines
+```
+
+Output format: `G [N]  code` where `G` = global line (use with `debug set`) and `[N]` = include-relative (for navigation only).
+
 ```bash
-abapgit-agent dump --date TODAY --detail 1    # inspect last crash
-abapgit-agent debug set --objects ZCL_FOO:42  # set breakpoint then attach
-abapgit-agent run --class ZCL_MY_RUNNER       # execute and inspect output
+# Example: METHOD do_something. starts at global line 87
+abapgit-agent debug set --objects ZCL_FOO:90   # set BP a few lines after METHOD statement
 ```
-→ See `guidelines/debug-dump.md` for dump analysis workflow
-→ See `guidelines/debug-session.md` for full debug session guide, breakpoint tips, and pull flow architecture
+
+Minimal correct sequence:
+```bash
+abapgit-agent debug set --objects ZCL_FOO:42        # 1. set breakpoint
+abapgit-agent debug attach --json > /tmp/a.json 2>&1 &   # 2. attach (background)
+until grep -q "Listener active" /tmp/a.json 2>/dev/null; do sleep 0.3; done
+abapgit-agent unit --files src/zcl_foo.clas.testclasses.abap > /tmp/t.json 2>&1 &  # 3. trigger
+# poll for session, then inspect
+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`
 
 ---
 
@@ -294,7 +346,7 @@ See **AI Tool Guidelines** below for how to react to each setting.
 ### Branch Workflow (`"mode": "branch"`)
 
 Always work on feature branches. Before every `pull`: rebase to default branch. On completion: create PR with squash merge.
-→ See `guidelines/branch-workflow.md` for step-by-step commands and examples
+→ See `guidelines/branch-workflow.md` — run: `abapgit-agent ref --topic branch-workflow`
 
 ### Trunk Workflow (`"mode": "trunk"`)
 
@@ -363,6 +415,12 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap
 1. ✗ Do not run `abapgit-agent transport create`
 2. ✓ Inform the user that transport creation is disabled for this project
 
+**When pull result contains `missing_abapgit_xml: true` (JSON mode) or warning about `.abapgit.xml`:**
+1. ✓ Inform the user that `.abapgit.xml` is missing from the repository root
+2. ✓ Suggest running `abapgit-agent init --package <PACKAGE>` to create it
+3. ✓ If `ACTIVATED_COUNT=0` with an empty log, suspect this as the cause
+4. ✗ Do not retry the pull — fix the missing file first
+
 **When `transports.allowRelease = false`:**
 1. ✗ Do not run `abapgit-agent transport release`
 2. ✓ Inform the user that transport release is disabled for this project
@@ -384,12 +442,19 @@ Modified ABAP files?
    └─ ✅ Use: skip syntax → commit → push → pull → (if errors: inspect)
 ```
 
-→ See `guidelines/workflow-detailed.md` for full workflow decision tree, error indicators, and complete command reference
+→ See `guidelines/workflow-detailed.md` — run: `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 |

package/abap/CLAUDE.slim.md

@@ -0,0 +1,42 @@
+# ABAP Development
+
+This project uses [abapgit-agent](https://github.com/SylvosCai/abapgit-agent) for ABAP development.
+
+## IMPORTANT: Before Writing Any ABAP Code
+
+Read the full ABAP development guide by running:
+
+```bash
+abapgit-agent guide
+```
+
+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
+
+## Accessing Guidelines
+
+Search by keyword to find which file covers a topic, then read the full file with `--topic`:
+
+```bash
+# Find files matching a keyword
+abapgit-agent ref "debug session"
+
+# Read a full guideline file by filename stem
+abapgit-agent ref --topic debug-session       # guidelines/debug-session.md
+abapgit-agent ref --topic workflow-detailed   # guidelines/workflow-detailed.md
+abapgit-agent ref --topic object-creation     # guidelines/object-creation.md
+abapgit-agent ref --topic branch-workflow     # guidelines/branch-workflow.md
+abapgit-agent ref --topic debug-dump          # guidelines/debug-dump.md
+abapgit-agent ref --topic run-probe-classes   # guidelines/run-probe-classes.md
+abapgit-agent ref --topic cds-testing         # guidelines/cds-testing.md
+
+# Also available: sql, cds, exceptions, json, testing, objects, abapgit, classes, ...
+abapgit-agent ref --list-topics
+```
+
+The `ref` command uses bundled guidelines automatically — no local `guidelines/` folder needed.
+
+## Project-Specific Naming Conventions
+
+See `guidelines/objects.local.md` for this project's naming convention overrides.

package/abap/guidelines/abapgit.md

@@ -20,8 +20,7 @@ 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           | zc_*.ddls.asddls            | zc_*.ddls.xml
-CDS Entity         | ze_*.ddlx.asddlx            | ze_*.ddlx.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
@@ -33,7 +32,7 @@ Key XML Settings:
   Class STATE:      1=Active
   Table TABCLASS:   TRANSP, POOL, CLUSTER
   Table DELIVERY:   A=Application, C=Customizing
-  CDS SOURCE_TYPE:  V=View, C=Consumption
+  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>
 ```
@@ -175,44 +174,12 @@ abapGit needs XML files to:
 
 ---
 
-### CDS View Entity (DDLS) - RECOMMENDED
-
-**Use by default when user says "create CDS view"**
-
-**Filename**: `src/zc_my_entity.ddls.xml`
-
-```xml
-<?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>
-   <DDLS>
-    <DDLNAME>ZC_MY_ENTITY</DDLNAME>
-    <DDLANGUAGE>E</DDLANGUAGE>
-    <DDTEXT>My CDS View Entity</DDTEXT>
-    <SOURCE_TYPE>W</SOURCE_TYPE>
-   </DDLS>
-  </asx:values>
- </asx:abap>
-</abapGit>
-```
-
-**Key Points for CDS View Entities**:
-1. **ABAP file extension**: Use `.ddls.asddls` (NOT `.ddls.abap`)
-2. **XML file**: Use `.ddls.xml`
-3. **DDLNAME**: Must match the CDS view entity name in the source
-4. **SOURCE_TYPE**: `W` = View Entity (modern, recommended)
-5. **Serializer**: Use `LCL_OBJECT_DDLS`
-6. **Source file**: Use `define view entity` (no `@AbapCatalog.sqlViewName`)
-
----
-
-### CDS View (DDLS) - Legacy Only
-
-**Only use when explicitly requested (e.g., "create legacy CDS view")**
+### CDS View / View Entity (DDLS)
 
 **Filename**: `src/zc_my_view.ddls.xml`
 
+The XML format is identical for both types — only `SOURCE_TYPE` differs:
+
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_DDLS" serializer_version="v1.0.0">
@@ -222,22 +189,17 @@ abapGit needs XML files to:
     <DDLNAME>ZC_MY_VIEW</DDLNAME>
     <DDLANGUAGE>E</DDLANGUAGE>
     <DDTEXT>My CDS View</DDTEXT>
-    <SOURCE_TYPE>V</SOURCE_TYPE>
+    <SOURCE_TYPE>W</SOURCE_TYPE>
    </DDLS>
   </asx:values>
  </asx:abap>
 </abapGit>
 ```
 
-**Key Points for CDS Views (Legacy)**:
-1. **ABAP file extension**: Use `.ddls.asddls` (NOT `.ddls.abap`)
-2. **XML file**: Use `.ddls.xml`
-3. **DDLNAME**: Must match the CDS view name in the source
-4. **SOURCE_TYPE**: `V` = View (legacy)
-5. **Serializer**: Use `LCL_OBJECT_DDLS`
-6. **Source file**: Must include `@AbapCatalog.sqlViewName` annotation
+- `SOURCE_TYPE W` → View Entity (`define view entity`, modern, **use by default**)
+- `SOURCE_TYPE V` → View (`define view` + `@AbapCatalog.sqlViewName`, legacy — only if explicitly requested)
 
-**For detailed comparison and usage guidance, see `guidelines/cds.md`**
+→ For DDL source syntax and full guidance: `abapgit-agent ref --topic cds-abapgit`
 
 ---