abapgit-agent 1.12.1 → 1.13.1

package/abap/guidelines/cds.md

@@ -8,7 +8,7 @@ grand_parent: ABAP Development
 
 # Creating CDS Views
 
-**Searchable keywords**: CDS, DDL, DDLS, CDS view, @AbapCatalog, @AccessControl, association, projection, consumption
+**Searchable keywords**: CDS, DDL, DDLS, CDS view, @AbapCatalog, @AccessControl, association, projection, consumption, GROUP BY, aggregation, subquery, JOIN
 
 ## TOPICS IN THIS FILE
 1. File Naming - line 96
@@ -145,20 +145,13 @@ where devclass not like '$%'
 
 1. **Avoid reserved words** - Field names like `PACKAGE`, `CLASS`, `INTERFACE` are reserved in CDS. Use alternatives like `PackageName`, `ClassName`.
 
-2. **Workflow for creating CDS views** - See `../CLAUDE.md` for complete workflow guidance:
-   - Independent CDS views: `syntax → commit → pull --files`
-   - Dependent CDS views (with associations to NEW views): Create underlying view first, then dependent view
-   - See CLAUDE.md section on "Working with dependent objects"
+2. **Workflow for creating CDS views** — run: `abapgit-agent ref --topic workflow-detailed`
 
 3. **System support** - CDS views require SAP systems with CDS capability (S/4HANA, SAP BW/4HANA, or ABAP 7.51+). Older systems will show error: "Object type DDLS is not supported by this system"
 
 ### Activating CDS Views
 
-**For standard workflow, see `../CLAUDE.md`**
-
-**CDS-specific notes:**
-- Single independent DDLS file: `abapgit-agent pull --files src/zc_view.ddls.asddls`
-- CDS views with associations to OTHER NEW views: Create target view first (see `../CLAUDE.md` for workflow)
+→ See `abapgit-agent ref --topic workflow-detailed` for the complete workflow.
 
 ## CDS View Entity Features
 
@@ -196,6 +189,39 @@ where devclass not like '$%'
 
 ## CDS Best Practices and Common Patterns
 
+### No Inline Subqueries — Use JOIN + GROUP BY Instead
+
+**CDS view entities do NOT support inline subqueries in JOIN.** This is a hard syntax error:
+
+❌ **WRONG — inline subquery (syntax error)**:
+```abap
+define view entity ZC_MyView as select from zheader as Header
+  inner join (                          // ← NOT SUPPORTED
+    select docid, sum( amount ) as Total
+    from zitems
+    group by docid
+  ) as Items on Items.docid = Header.docid ...
+```
+
+✅ **CORRECT — JOIN base tables directly, use GROUP BY on the outer view**:
+```abap
+define view entity ZC_MyView
+  as select from zheader as Header
+    inner join zitems as Item
+      on Item.docid = Header.docid
+{
+  key Header.docid       as DocId,
+      Header.description as Description,
+      count(*)           as NumberOfItems,
+      sum(Item.amount)   as TotalAmount
+}
+group by Header.docid, Header.description
+```
+
+**This works.** CDS supports JOIN + GROUP BY + aggregation functions in a single view. Only inline subqueries in the FROM/JOIN clause are unsupported.
+
+---
+
 ### Key Field Ordering (STRICT RULE)
 
 CDS views enforce strict key field ordering that differs from regular SQL:
@@ -235,6 +261,8 @@ CDS views enforce strict key field ordering that differs from regular SQL:
 
 ### Currency/Amount Field Aggregation
 
+> **Design principle**: Prefer a **single CDS view** with JOIN + GROUP BY. Only split into multiple layered views when requirements specifically need reusable intermediate aggregations shared across different consumers.
+
 When aggregating currency or amount fields in CDS views, use semantic annotations instead of complex casting:
 
 ❌ **WRONG - Complex casting (will fail)**:

package/abap/guidelines/testing.md

@@ -290,6 +290,49 @@ METHOD test_aggregation.
 ENDMETHOD.
 ```
 
+### Testing CDS Views that Select from Another CDS View
+
+> **Note:** This pattern applies when your design **already has** a CDS view that selects from another CDS view. It does NOT mean you should split a single view into two — use a single CDS view with GROUP BY / JOIN when the business logic fits.
+
+When your CDS view selects from **another CDS view** (not a base table), `create` will raise `CX_CDS_FAILURE`. Use `create_for_multiple_cds` instead and list all CDS entities in the dependency chain.
+
+```abap
+METHOD class_setup.
+  " ZC_TopView selects from ZC_IntermediateView (another CDS view entity)
+  " → must use create_for_multiple_cds and list all CDS entities
+  mo_cds_env_static = cl_cds_test_environment=>create_for_multiple_cds(
+    i_for_entities = VALUE #(
+      ( 'ZC_TOPVIEW' )           " the view under test
+      ( 'ZC_INTERMEDIATEVIEW' )  " the CDS view it selects from
+    ) ).
+ENDMETHOD.
+```
+
+Insert test data into the intermediate CDS view (not the base tables), since that is what the top-level view reads:
+
+```abap
+METHOD test_read.
+  DATA lt_source TYPE TABLE OF zc_intermediateview WITH EMPTY KEY.
+  lt_source = VALUE #(
+    ( field1 = 'A' field2 = 100 )
+    ( field1 = 'B' field2 = 200 ) ).
+  mo_cds_env->insert_test_data( i_data = lt_source ).
+
+  SELECT * FROM zc_topview INTO TABLE @DATA(lt_result).
+
+  cl_abap_unit_assert=>assert_equals(
+    exp = 2  act = lines( lt_result )  msg = 'Expected 2 rows' ).
+ENDMETHOD.
+```
+
+**Rules:**
+- List the view under test **and all CDS views it depends on** in `i_for_entities`
+- Insert data into the **direct source** of the top-level view (the intermediate CDS view)
+- Order in `i_for_entities` does not matter
+- If you get `CX_CDS_FAILURE` when using `create`, switch to `create_for_multiple_cds`
+
+---
+
 ### Key Classes for CDS Testing
 
 | Item | Type/Usage |
@@ -304,7 +347,8 @@ ENDMETHOD.
 
 | Method | Purpose |
 |--------|---------|
-| `CL_CDS_TEST_ENVIRONMENT=>create( i_for_entity = ... )` | Create test environment (returns `if_cds_test_environment`) |
+| `CL_CDS_TEST_ENVIRONMENT=>create( i_for_entity = ... )` | Create test environment for a CDS view over base tables |
+| `CL_CDS_TEST_ENVIRONMENT=>create_for_multiple_cds( i_for_entities = ... )` | Create test environment when the CDS view selects from another CDS view |
 | `insert_test_data( i_data = ... )` | Insert test data into test doubles |
 | `clear_doubles` | Clear test data before each test method |
 | `destroy` | Clean up after test class |
@@ -314,7 +358,7 @@ ENDMETHOD.
 1. **Use interface type**: `DATA mo_cds_env TYPE REF TO if_cds_test_environment` - the CREATE method returns an interface reference
 2. **CLASS-METHODS required**: `class_setup` and `class_teardown` must be declared with `CLASS-METHODS` (not `METHODS`)
 3. **Table type declaration**: Must declare `DATA lt_tab TYPE TABLE OF <type> WITH EMPTY KEY` before using `VALUE #()`
-4. **Auto-created dependencies**: CDS framework auto-creates test doubles for base tables - do not specify `i_dependency_list`
+4. **Auto-created dependencies**: When the CDS view selects only from **base tables**, the framework auto-creates test doubles — do not specify `i_dependency_list`. When the CDS view selects from **another CDS view**, use `create_for_multiple_cds` instead (see section below).
 5. **Aggregations**: For CDS views with SUM/COUNT/GROUP BY, insert test data into base tables (SFLIGHT, SCARR, etc.)
 6. **Clear doubles**: Call `clear_doubles` in `setup` method before each test
 7. **Enable associations**: Set `test_associations = 'X'` only if testing CDS associations

package/bin/abapgit-agent

@@ -54,6 +54,7 @@ async function main() {
     debug: require('../src/commands/debug'),
     run: require('../src/commands/run'),
     ref: require('../src/commands/ref'),
+    guide: require('../src/commands/guide'),
     init: require('../src/commands/init'),
     pull: require('../src/commands/pull'),
     upgrade: require('../src/commands/upgrade'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.12.1",
+  "version": "1.13.1",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [
@@ -8,7 +8,9 @@
     "src/",
     "abap/guidelines/",
     "abap/CLAUDE.md",
+    "abap/CLAUDE.slim.md",
     "abap/.github/copilot-instructions.md",
+    "abap/.github/copilot-instructions.slim.md",
     ".abapGitAgent.example"
   ],
   "bin": {

package/src/commands/guide.js

@@ -0,0 +1,207 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+module.exports = {
+  name: 'guide',
+  description: 'Show bundled ABAP development guide',
+  requiresAbapConfig: false,
+
+  _findBundledGuide() {
+    const candidates = [
+      path.join(__dirname, '..', '..', 'abap', 'CLAUDE.md'),
+      path.join(__dirname, '..', '..', '..', 'abap', 'CLAUDE.md')
+    ];
+    return candidates.find(p => fs.existsSync(p)) || null;
+  },
+
+  _findSlimStub() {
+    const candidates = [
+      path.join(__dirname, '..', '..', 'abap', 'CLAUDE.slim.md'),
+      path.join(__dirname, '..', '..', '..', 'abap', 'CLAUDE.slim.md')
+    ];
+    return candidates.find(p => fs.existsSync(p)) || null;
+  },
+
+  _findCopilotSlimStub() {
+    const candidates = [
+      path.join(__dirname, '..', '..', 'abap', '.github', 'copilot-instructions.slim.md'),
+      path.join(__dirname, '..', '..', '..', 'abap', '.github', 'copilot-instructions.slim.md')
+    ];
+    return candidates.find(p => fs.existsSync(p)) || null;
+  },
+
+  async _confirm(question) {
+    return new Promise((resolve) => {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      rl.question(question, (answer) => {
+        rl.close();
+        const normalized = answer.trim().toLowerCase();
+        resolve(normalized === '' || normalized === 'y' || normalized === 'yes');
+      });
+    });
+  },
+
+  async _runMigrate(args) {
+    const dryRun = args.includes('--dry-run');
+    const yes = args.includes('--yes') || args.includes('-y');
+    const cwd = process.cwd();
+
+    const slimStubPath = this._findSlimStub();
+    const copilotSlimStubPath = this._findCopilotSlimStub();
+
+    // --- Scan guidelines/: delete all *.md except *.local.md ---
+    const guidelinesDir = path.join(cwd, 'guidelines');
+    const toDelete = [];
+    const toKeep = [];
+
+    if (fs.existsSync(guidelinesDir)) {
+      for (const name of fs.readdirSync(guidelinesDir)) {
+        if (!name.endsWith('.md')) continue;
+        if (name.endsWith('.local.md')) {
+          toKeep.push(name);
+        } else {
+          toDelete.push(path.join(guidelinesDir, name));
+        }
+      }
+    }
+
+    // --- CLAUDE.md: replace if it exists ---
+    const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+    const claudeExists = fs.existsSync(claudeMdPath);
+
+    // --- .github/copilot-instructions.md: replace if it exists ---
+    const copilotMdPath = path.join(cwd, '.github', 'copilot-instructions.md');
+    const copilotExists = fs.existsSync(copilotMdPath);
+
+    // --- Nothing to do? ---
+    const nothingToDo = toDelete.length === 0 && !claudeExists && !copilotExists;
+    if (nothingToDo) {
+      console.log('');
+      console.log('✅ Nothing to migrate — no guideline files, CLAUDE.md, or copilot-instructions.md found.');
+      console.log('');
+      return;
+    }
+
+    // --- Preview ---
+    console.log('');
+    console.log('🔄 guide --migrate: switch to bundled guidelines');
+    console.log('');
+
+    if (toDelete.length > 0) {
+      console.log(`Files to remove (${toDelete.length} guideline file${toDelete.length > 1 ? 's' : ''}):`);
+      toDelete.forEach(f => console.log(`   ${path.relative(cwd, f)}`));
+      console.log('');
+    }
+
+    if (toKeep.length > 0) {
+      console.log('Files to keep (project-specific):');
+      toKeep.forEach(f => console.log(`   guidelines/${f}`));
+      console.log('');
+    }
+
+    if (claudeExists) {
+      if (slimStubPath) {
+        console.log('CLAUDE.md → will replace with slim stub');
+        console.log("   (run 'abapgit-agent guide' to read the full guide on demand)");
+      } else {
+        console.log('CLAUDE.md → ⚠️  slim stub not found, will skip');
+      }
+      console.log('');
+    }
+
+    if (copilotExists) {
+      if (copilotSlimStubPath) {
+        console.log('.github/copilot-instructions.md → will replace with slim stub');
+      } else {
+        console.log('.github/copilot-instructions.md → ⚠️  slim stub not found, will skip');
+      }
+      console.log('');
+    }
+
+    const dirWillBeEmpty = fs.existsSync(guidelinesDir) && toKeep.length === 0;
+    if (dirWillBeEmpty) {
+      console.log('guidelines/ will be removed (no project-specific files remain).');
+      console.log('');
+    }
+
+    if (dryRun) {
+      console.log('ℹ️  Dry run — no changes made.');
+      console.log('');
+      return;
+    }
+
+    // --- Confirm ---
+    if (!yes) {
+      const proceed = await this._confirm('Proceed? [y/N] ');
+      if (!proceed) {
+        console.log('Migration cancelled.');
+        console.log('');
+        return;
+      }
+    }
+
+    // --- Execute ---
+    console.log('');
+
+    for (const filePath of toDelete) {
+      fs.unlinkSync(filePath);
+      console.log(`🗑️  Removed ${path.relative(cwd, filePath)}`);
+    }
+
+    if (dirWillBeEmpty) {
+      const remaining = fs.readdirSync(guidelinesDir);
+      if (remaining.length === 0) {
+        fs.rmdirSync(guidelinesDir);
+        console.log('🗑️  Removed guidelines/');
+      }
+    }
+
+    if (claudeExists && slimStubPath) {
+      const slimContent = fs.readFileSync(slimStubPath, 'utf8');
+      fs.writeFileSync(claudeMdPath, slimContent);
+      console.log('✅ Replaced CLAUDE.md with slim stub');
+    }
+
+    if (copilotExists && copilotSlimStubPath) {
+      const slimContent = fs.readFileSync(copilotSlimStubPath, 'utf8');
+      fs.writeFileSync(copilotMdPath, slimContent);
+      console.log('✅ Replaced .github/copilot-instructions.md with slim stub');
+    }
+
+    console.log('');
+    console.log('✅ Migration complete.');
+    console.log('   Standard guidelines are now read from the package automatically.');
+    console.log("   Run 'abapgit-agent ref \"<pattern>\"' or 'abapgit-agent ref --topic <topic>' to search them.");
+    console.log('');
+  },
+
+  async execute(args) {
+    if (args.includes('--migrate')) {
+      return this._runMigrate(args);
+    }
+
+    const filePath = this._findBundledGuide();
+
+    if (!filePath) {
+      console.error('❌ Bundled CLAUDE.md not found. Make sure abapgit-agent is properly installed.');
+      process.exit(1);
+    }
+
+    if (args.includes('--path')) {
+      console.log(filePath);
+      return;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    if (args.includes('--json')) {
+      console.log(JSON.stringify({ path: filePath, content }));
+      return;
+    }
+
+    console.log(content);
+  }
+};

package/src/commands/help.js

@@ -78,6 +78,19 @@ Commands:
     - Use full URL: https://github.com/user/repo.git
     - Or short name: user/repo or user/repo (assumes github.com)
 
+  guide [--path] [--json]
+    Show the full ABAP development guide bundled with the package.
+    Reads directly from the installed npm package — always up-to-date.
+    - Use --path to print only the file path (useful for pagers)
+    - Use --json for machine-readable output
+
+  guide --migrate [--dry-run] [--yes]
+    Migrate repo from locally-copied guidelines to bundled fallback.
+    Removes standard guideline files copied by old 'init', replaces full CLAUDE.md
+    with slim stub. Project-specific files (*.local.md) are never removed.
+    - Use --dry-run to preview changes without applying them
+    - Use --yes to skip confirmation prompt
+
   health
     Check if ABAP REST API is healthy
 
@@ -107,6 +120,8 @@ Examples:
   abapgit-agent dump --user DEVELOPER --detail 1             # Full detail of first result
   abapgit-agent ref "CORRESPONDING"                          # Search for pattern
   abapgit-agent ref --topic exceptions                       # View exceptions topic
+  abapgit-agent guide                                        # Full ABAP dev guide
+  abapgit-agent guide --path                                 # Path to guide file
   abapgit-agent health                                       # Health check
   abapgit-agent status                                       # Configuration status
 

package/src/commands/init.js

@@ -202,34 +202,82 @@ Examples:
       console.log(`\n🔄 Updating abapGit Agent files`);
       console.log('');
 
-      // Copy CLAUDE.md
-      await copyFileIfExists(
-        pathModule.join(__dirname, '..', '..', 'abap', 'CLAUDE.md'),
-        pathModule.join(process.cwd(), 'CLAUDE.md'),
-        'CLAUDE.md'
-      );
-
-      // Copy copilot-instructions.md
-      await copyFileIfExists(
-        pathModule.join(__dirname, '..', '..', 'abap', '.github', 'copilot-instructions.md'),
-        pathModule.join(process.cwd(), '.github', 'copilot-instructions.md'),
-        '.github/copilot-instructions.md',
-        true  // create parent dir
-      );
-
-      // Copy guidelines folder to project root
-      await copyGuidelinesFolder(
-        pathModule.join(__dirname, '..', '..', 'abap', 'guidelines'),
-        pathModule.join(process.cwd(), 'guidelines'),
-        true  // overwrite
-      );
-
-      // Detect and offer to remove old numbered guideline files
-      await cleanupOldGuidelineFiles(pathModule.join(process.cwd(), 'guidelines'));
+      // copilot-instructions.md: never overwrite — user may have customised it
+      const localCopilotMdPath = pathModule.join(process.cwd(), '.github', 'copilot-instructions.md');
+      if (!fs.existsSync(localCopilotMdPath)) {
+        await copyFileIfExists(
+          pathModule.join(__dirname, '..', '..', 'abap', '.github', 'copilot-instructions.slim.md'),
+          localCopilotMdPath,
+          '.github/copilot-instructions.md',
+          true  // create parent dir
+        );
+      } else {
+        console.log(`⚠️  .github/copilot-instructions.md already exists, skipped`);
+      }
+
+      // CLAUDE.md: never overwrite — user may have customised it
+      const localClaudeMdPath = pathModule.join(process.cwd(), 'CLAUDE.md');
+      if (!fs.existsSync(localClaudeMdPath)) {
+        await copyFileIfExists(
+          pathModule.join(__dirname, '..', '..', 'abap', 'CLAUDE.slim.md'),
+          localClaudeMdPath,
+          'CLAUDE.md'
+        );
+      } else {
+        console.log(`⚠️  CLAUDE.md already exists, skipped (use 'abapgit-agent guide --migrate' to replace a full guide with the slim stub)`);
+      }
+
+      // guidelines/: never copy standard files — they're bundled in the package now.
+      // Only ensure objects.local.md stub exists if missing.
+      const guidelinesDestPath = pathModule.join(process.cwd(), 'guidelines');
+      if (!fs.existsSync(guidelinesDestPath)) {
+        fs.mkdirSync(guidelinesDestPath, { recursive: true });
+        console.log(`✅ Created guidelines/`);
+      }
+      const localNamingPath = pathModule.join(guidelinesDestPath, 'objects.local.md');
+      if (!fs.existsSync(localNamingPath)) {
+        // reuse the same stub content as init
+        const localNamingStub = `---
+nav_order: 8
+---
+
+# Project Naming Conventions (Override)
+
+This file overrides \`guidelines/objects.md\` for this project.
+It is **never overwritten** by \`abapgit-agent init --update\` — safe to customise.
+
+Searched by the \`ref\` command alongside all other guidelines.
+
+## Naming Conventions
+
+Uncomment and edit the rows that differ from the defaults in \`guidelines/objects.md\`:
+
+| 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 |
+`;
+        fs.writeFileSync(localNamingPath, localNamingStub);
+        console.log(`✅ Created guidelines/objects.local.md`);
+      } else {
+        console.log(`⚠️  guidelines/objects.local.md already exists, skipped`);
+      }
+
+      // Detect and offer to remove old numbered guideline files (legacy cleanup)
+      await cleanupOldGuidelineFiles(guidelinesDestPath);
 
       console.log(`
 📋 Update complete!
-   Run 'abapgit-agent ref --list-topics' to see available topics.
+   Standard guidelines are read from the package automatically — no local copies needed.
+   Run 'abapgit-agent guide --migrate' if you still have copied guideline files to remove.
 `);
       return;
     }
@@ -386,66 +434,55 @@ Examples:
       console.log(`✅ .gitignore already up to date`);
     }
 
-    // Copy CLAUDE.md
-    const claudeMdPath = pathModule.join(__dirname, '..', '..', 'abap', 'CLAUDE.md');
+    // Copy CLAUDE.md (slim stub — tells Claude to run 'abapgit-agent guide')
+    const claudeMdPath = pathModule.join(__dirname, '..', '..', 'abap', 'CLAUDE.slim.md');
     const localClaudeMdPath = pathModule.join(process.cwd(), 'CLAUDE.md');
     try {
-      if (fs.existsSync(claudeMdPath)) {
+      if (fs.existsSync(localClaudeMdPath)) {
+        console.log(`⚠️  CLAUDE.md already exists, skipped`);
+      } else if (fs.existsSync(claudeMdPath)) {
         fs.copyFileSync(claudeMdPath, localClaudeMdPath);
         console.log(`✅ Created CLAUDE.md`);
       } else {
-        console.log(`⚠️  CLAUDE.md not found in abap/ directory`);
+        console.log(`⚠️  CLAUDE.slim.md not found in abap/ directory`);
       }
     } catch (error) {
       console.error(`Error copying CLAUDE.md: ${error.message}`);
     }
 
-    // Copy copilot-instructions.md for GitHub Copilot
-    const copilotMdPath = pathModule.join(__dirname, '..', '..', 'abap', '.github', 'copilot-instructions.md');
+    // Copy copilot-instructions.md for GitHub Copilot (slim stub)
+    const copilotMdPath = pathModule.join(__dirname, '..', '..', 'abap', '.github', 'copilot-instructions.slim.md');
     const githubDir = pathModule.join(process.cwd(), '.github');
     const localCopilotMdPath = pathModule.join(githubDir, 'copilot-instructions.md');
     try {
-      if (fs.existsSync(copilotMdPath)) {
-        // Ensure .github directory exists
+      if (fs.existsSync(localCopilotMdPath)) {
+        console.log(`⚠️  .github/copilot-instructions.md already exists, skipped`);
+      } else if (fs.existsSync(copilotMdPath)) {
         if (!fs.existsSync(githubDir)) {
           fs.mkdirSync(githubDir, { recursive: true });
         }
         fs.copyFileSync(copilotMdPath, localCopilotMdPath);
         console.log(`✅ Created .github/copilot-instructions.md`);
       } else {
-        console.log(`⚠️  copilot-instructions.md not found in abap/ directory`);
+        console.log(`⚠️  copilot-instructions.slim.md not found in abap/.github/ directory`);
       }
     } catch (error) {
       console.error(`Error copying copilot-instructions.md: ${error.message}`);
     }
 
-    // Copy guidelines folder to project root
-    const guidelinesSrcPath = pathModule.join(__dirname, '..', '..', 'abap', 'guidelines');
+    // Create guidelines/ directory and objects.local.md stub
+    // (Standard guidelines are bundled in the package — no need to copy them)
     const guidelinesDestPath = pathModule.join(process.cwd(), 'guidelines');
     try {
-      if (fs.existsSync(guidelinesSrcPath)) {
-        if (!fs.existsSync(guidelinesDestPath)) {
-          // Create guidelines directory
-          fs.mkdirSync(guidelinesDestPath, { recursive: true });
-          // Copy all files from guidelines folder
-          const files = fs.readdirSync(guidelinesSrcPath);
-          for (const file of files) {
-            if (file.endsWith('.md')) {
-              fs.copyFileSync(
-                pathModule.join(guidelinesSrcPath, file),
-                pathModule.join(guidelinesDestPath, file)
-              );
-            }
-          }
-          console.log(`✅ Created guidelines/ (${files.filter(f => f.endsWith('.md')).length} files)`);
-        } else {
-          console.log(`⚠️  guidelines/ already exists, skipped`);
-        }
+      if (!fs.existsSync(guidelinesDestPath)) {
+        fs.mkdirSync(guidelinesDestPath, { recursive: true });
+        console.log(`✅ Created guidelines/`);
+      }
 
-        // Create objects.local.md stub if not already present
-        const localNamingPath = pathModule.join(guidelinesDestPath, 'objects.local.md');
-        if (!fs.existsSync(localNamingPath)) {
-          const localNamingStub = `---
+      // Create objects.local.md stub if not already present
+      const localNamingPath = pathModule.join(guidelinesDestPath, 'objects.local.md');
+      if (!fs.existsSync(localNamingPath)) {
+        const localNamingStub = `---
 nav_order: 8
 ---
 
@@ -473,14 +510,11 @@ Uncomment and edit the rows that differ from the defaults in \`guidelines/object
 | Structure | Z | ZMY_STRUCTURE |
 | Table Type | Z | ZMY_TABLE_TYPE |
 `;
-          fs.writeFileSync(localNamingPath, localNamingStub);
-          console.log(`✅ Created guidelines/objects.local.md (project naming conventions)`);
-        }
-      } else {
-        console.log(`⚠️  guidelines folder not found in abap/ directory`);
+        fs.writeFileSync(localNamingPath, localNamingStub);
+        console.log(`✅ Created guidelines/objects.local.md (project naming conventions)`);
       }
     } catch (error) {
-      console.error(`Error copying guidelines: ${error.message}`);
+      console.error(`Error creating guidelines: ${error.message}`);
     }
 
     // Create folder
@@ -533,6 +567,11 @@ Uncomment and edit the rows that differ from the defaults in \`guidelines/object
    1. Edit .abapGitAgent with your ABAP credentials (host, user, password)
    2. Run 'abapgit-agent create --import' to create online repository
    3. Run 'abapgit-agent pull' to activate objects
+
+💡 Tips:
+   • Only guidelines/objects.local.md needs to live in your repo.
+     Standard guidelines are read from the package automatically via 'ref'.
+   • Run 'abapgit-agent guide' to read the full ABAP development guide.
 `);
   }
 };

package/src/commands/pull.js

@@ -323,6 +323,13 @@ module.exports = {
       if (success === 'X' || success === true) {
         console.log(`✅ Pull completed successfully!`);
         console.log(`   Message: ${message || 'N/A'}`);
+      } else if (failedCount === 0 && failedObjects.length === 0 &&
+                 activatedCount === 0 && logMessages.length === 0 &&
+                 (!message || /activation cancelled|nothing to activate|already active/i.test(message))) {
+        // abapGit returns SUCCESS='' with "Activation cancelled" when there are
+        // no inactive objects to activate — the object is already active and consistent.
+        console.log(`✅ Pull completed — object already active, nothing to activate.`);
+        console.log(`   Message: ${message || 'N/A'}`);
       } else {
         console.error(`❌ Pull completed with errors!`);
         console.error(`   Message: ${message || 'N/A'}`);
@@ -431,8 +438,12 @@ module.exports = {
         console.log(`\n❌ Failed Objects Log (${failedCount})`);
       }
 
-      // Throw if pull was not successful so callers (e.g. upgrade) can detect failure
-      if (success !== 'X' && success !== true) {
+      // Throw if pull was not successful so callers (e.g. upgrade) can detect failure.
+      // Exception: SUCCESS='' with no failures and no log = object already active, not a real error.
+      const alreadyActive = failedCount === 0 && failedObjects.length === 0 &&
+                            activatedCount === 0 && logMessages.length === 0 &&
+                            (!message || /activation cancelled|nothing to activate|already active/i.test(message));
+      if (success !== 'X' && success !== true && !alreadyActive) {
         const err = new Error(message || 'Pull completed with errors');
         err._isPullError = true;
         throw err;