a2acalling 0.6.55 → 0.6.57

package/CLAUDE-INSTALL.md

@@ -152,3 +152,5 @@ a2a version              # Show installed version
 - Disclosure: `~/.config/openclaw/a2a-disclosure.json`
 - Native app: `~/Applications/A2A Callbook.app` (macOS only)
 - Dashboard: `http://127.0.0.1:<port>/dashboard/`
+
+<!-- END A2A CALLING SECTION -->

package/bin/cli.js

@@ -2711,6 +2711,62 @@ a2a add "${inviteUrl}" "${ownerText || 'friend'}" && a2a call "${ownerText || 'f
       console.log('Removing database... ⏭️');
     }
 
+    // ── Remove installed skill files using the shared cleanup module ──────
+    //
+    // The postinstall script writes .a2a-manifest.json listing every file it
+    // installed. We delegate to the shared cleanupProjectFiles() function which
+    // handles CLAUDE.md section removal, file deletion, and empty directory
+    // cleanup. This is the same logic used by the npm preuninstall hook,
+    // ensuring both uninstall paths behave identically.
+    //
+    // We check multiple candidate directories for the manifest because `a2a
+    // uninstall` might be run from a different directory than the one where
+    // the package was originally installed.
+    const manifestCandidates = [
+      process.env.INIT_CWD,
+      process.cwd(),
+    ].filter(Boolean);
+    // Deduplicate paths (INIT_CWD and cwd may be identical)
+    const uniqueDirs = [...new Set(manifestCandidates.map(d => path.resolve(d)))];
+
+    let projectCleaned = false;
+    for (const candidateDir of uniqueDirs) {
+      if (fs.existsSync(path.join(candidateDir, '.a2a-manifest.json'))) {
+        process.stdout.write('Removing installed skill files... ');
+        try {
+          const { cleanupProjectFiles } = require('../scripts/cleanup');
+          const cleanResult = cleanupProjectFiles(candidateDir);
+          const hasErrors = cleanResult.errors.length > 0;
+          console.log(hasErrors ? '⚠️' : '✅');
+          if (cleanResult.removed.length > 0) {
+            for (const f of cleanResult.removed) {
+              console.log(`  - ${f}`);
+            }
+          }
+          if (cleanResult.preserved.length > 0) {
+            for (const f of cleanResult.preserved) {
+              console.log(`  ~ ${f}`);
+            }
+          }
+          if (hasErrors) {
+            for (const e of cleanResult.errors) {
+              console.error(`  ! ${e}`);
+            }
+          }
+          projectCleaned = true;
+        } catch (err) {
+          console.log('⚠️');
+          console.error(`  Cleanup error: ${err.message}`);
+        }
+        break; // Only clean up once — first manifest found wins
+      }
+    }
+    if (!projectCleaned) {
+      // No manifest found in any candidate directory. This is expected when
+      // `a2a uninstall` is run after `npm uninstall` (preuninstall already cleaned).
+      console.log('Removing installed skill files... ⏭️  (no manifest found)');
+    }
+
     // Remove native macOS app if present
     if (os.platform() === 'darwin') {
       const appCandidates = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2acalling",
-  "version": "0.6.55",
+  "version": "0.6.57",
   "description": "Agent-to-agent calling for OpenClaw - A2A agent communication",
   "main": "src/index.js",
   "bin": {

package/scripts/cleanup.js

@@ -0,0 +1,251 @@
+// ============================================================================
+// Shared cleanup function used by both:
+//   1. npm preuninstall hook (scripts/preuninstall.js)
+//   2. `a2a uninstall` CLI command (bin/cli.js)
+//
+// Reads .a2a-manifest.json to determine which files to remove.
+// CLAUDE.md section removal uses the same boundary markers as the
+// merge logic in installSkills() — "# A2A Calling" start marker
+// and "<!-- END A2A CALLING SECTION -->" end marker.
+//
+// Returns { removed: string[], preserved: string[], errors: string[] }
+// so callers can print a meaningful summary.
+// ============================================================================
+
+const fs = require('fs');
+const path = require('path');
+
+// These markers must match the ones used in install-skills.js merge logic.
+// If they diverge, cleanup will fail to find the section boundaries.
+const A2A_SECTION_START = '# A2A Calling';
+const A2A_SECTION_END = '<!-- END A2A CALLING SECTION -->';
+
+/**
+ * cleanupProjectFiles — manifest-driven removal of all postinstall artifacts
+ *
+ * Reads .a2a-manifest.json from targetDir, then removes every file listed in
+ * the manifest. CLAUDE.md gets special handling: only the A2A section is
+ * removed, preserving any user content before/after. Empty directories
+ * (.claude/commands/, .claude/) are cleaned up if no non-a2a files remain.
+ *
+ * @param {string} targetDir - The project directory containing .a2a-manifest.json
+ * @returns {{ removed: string[], preserved: string[], errors: string[] }}
+ */
+function cleanupProjectFiles(targetDir) {
+  const result = { removed: [], preserved: [], errors: [] };
+  const manifestPath = path.join(targetDir, '.a2a-manifest.json');
+
+  // If manifest doesn't exist, skip cleanup gracefully.
+  // This happens for manual installs, old versions, or projects where the
+  // manifest was already cleaned up. Better to leave files than crash.
+  if (!fs.existsSync(manifestPath)) {
+    return result;
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (err) {
+    // Corrupt or unreadable manifest — can't determine what to clean up.
+    // Return gracefully so npm uninstall doesn't fail.
+    result.errors.push(`.a2a-manifest.json: could not parse (${err.message})`);
+    return result;
+  }
+
+  const files = manifest.files || [];
+
+  for (const entry of files) {
+    // Skip the manifest itself — we remove it last, after all other files
+    if (entry.path === '.a2a-manifest.json') continue;
+
+    const filePath = path.join(targetDir, entry.path);
+
+    // If a file listed in manifest doesn't exist on disk, skip it silently.
+    // This handles cases where the user manually deleted files, or a previous
+    // partial cleanup already removed some files.
+    if (!fs.existsSync(filePath)) continue;
+
+    // ── CLAUDE.md: section removal, not whole-file deletion ──────────────
+    //
+    // The user may have their own project-specific content in CLAUDE.md.
+    // We only remove the A2A section (bounded by start/end markers), leaving
+    // everything else intact.
+    if (entry.path === 'CLAUDE.md') {
+      try {
+        const cleaned = removeA2ASectionFromClaudeMd(filePath);
+        if (cleaned === 'deleted') {
+          result.removed.push('CLAUDE.md (was A2A-only, deleted entirely)');
+        } else if (cleaned === 'trimmed') {
+          result.preserved.push('CLAUDE.md (A2A section removed, user content preserved)');
+        } else {
+          // 'no-section' — CLAUDE.md exists but has no A2A section.
+          // This shouldn't happen if the manifest says it was installed, but
+          // could occur if the user manually edited it. Leave it alone.
+          result.preserved.push('CLAUDE.md (no A2A section found, left unchanged)');
+        }
+      } catch (err) {
+        result.errors.push(`CLAUDE.md: ${err.message}`);
+      }
+      continue;
+    }
+
+    // ── All other files: delete entirely ─────────────────────────────────
+    try {
+      fs.rmSync(filePath, { force: true });
+      result.removed.push(entry.path);
+    } catch (err) {
+      // If file permissions prevent deletion, log warning and continue.
+      // We don't want a single permission error to abort the entire cleanup.
+      result.errors.push(`${entry.path}: ${err.message}`);
+    }
+  }
+
+  // ── Empty directory cleanup ──────────────────────────────────────────────
+  //
+  // After removing .claude/commands/a2a-*.md and .claude/a2a-skill-reference.md,
+  // the directories may be empty. We clean them up to avoid leaving empty dirs,
+  // but ONLY if they contain no non-a2a files (user's own commands, settings, etc.).
+  cleanupEmptyDir(path.join(targetDir, '.claude', 'commands'), result);
+  cleanupEmptyDir(path.join(targetDir, '.claude'), result);
+  cleanupEmptyDir(path.join(targetDir, '.codex'), result);
+
+  // ── Remove the install log ───────────────────────────────────────────────
+  //
+  // .a2a-install.log is written by postinstall.js as a convenience log.
+  // It's listed in the manifest but we also try to remove it explicitly
+  // in case the manifest entry was missing (belt and suspenders).
+  const logPath = path.join(targetDir, '.a2a-install.log');
+  if (fs.existsSync(logPath)) {
+    try {
+      fs.rmSync(logPath, { force: true });
+      // Only add to removed list if not already tracked from manifest iteration
+      if (!result.removed.includes('.a2a-install.log')) {
+        result.removed.push('.a2a-install.log');
+      }
+    } catch (err) {
+      result.errors.push(`.a2a-install.log: ${err.message}`);
+    }
+  }
+
+  // ── Remove the manifest itself last ──────────────────────────────────────
+  //
+  // The manifest is the cleanup driver, so we remove it after everything else.
+  // If this fails, the manifest is left behind — which is acceptable since
+  // a stale manifest is harmless and helps debug failed cleanups.
+  try {
+    fs.rmSync(manifestPath, { force: true });
+    result.removed.push('.a2a-manifest.json');
+  } catch (err) {
+    result.errors.push(`.a2a-manifest.json: ${err.message}`);
+  }
+
+  return result;
+}
+
+/**
+ * removeA2ASectionFromClaudeMd — surgically removes the A2A section from CLAUDE.md
+ *
+ * Three outcomes:
+ *   - 'deleted'    : File was entirely A2A content, deleted the file
+ *   - 'trimmed'    : A2A section removed, remaining user content preserved
+ *   - 'no-section' : No A2A section found (file left unchanged)
+ *
+ * Edge case: CLAUDE.md becomes empty after A2A section removal.
+ * If the only content was the A2A section, the file would be left as
+ * whitespace-only, which is confusing. Delete it entirely instead.
+ *
+ * Edge case: Legacy installs without end marker.
+ * Pre-A2A-34 installs wrote the A2A section without the
+ * <!-- END A2A CALLING SECTION --> marker. For these, we fall back
+ * to removing from "# A2A Calling" to EOF, same as the old merge
+ * replacement behavior. This means any user content added after the
+ * A2A section in a legacy install will be lost — but this is the
+ * same behavior they already had on upgrade, so it's not a regression.
+ */
+function removeA2ASectionFromClaudeMd(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  // If the A2A section start marker isn't present, nothing to remove
+  if (!content.includes(A2A_SECTION_START)) {
+    return 'no-section';
+  }
+
+  const sectionStart = content.indexOf(A2A_SECTION_START);
+  const endMarkerIndex = content.indexOf(A2A_SECTION_END, sectionStart);
+
+  let before, after;
+
+  if (endMarkerIndex !== -1) {
+    // End marker found — extract content before and after the bounded section.
+    // trimEnd/trimStart collapse the whitespace gap left by the removed section.
+    const sectionEnd = endMarkerIndex + A2A_SECTION_END.length;
+    before = content.slice(0, sectionStart).trimEnd();
+    after = content.slice(sectionEnd).trimStart();
+  } else {
+    // Legacy install without end marker — remove from header to EOF.
+    // Everything after "# A2A Calling" is considered part of the A2A section.
+    before = content.slice(0, sectionStart).trimEnd();
+    after = '';
+  }
+
+  // Reassemble the file from the non-A2A portions
+  let cleaned;
+  if (before && after) {
+    // Content exists both before and after — join with double newline
+    cleaned = before + '\n\n' + after;
+  } else if (before) {
+    cleaned = before;
+  } else if (after) {
+    cleaned = after;
+  } else {
+    cleaned = '';
+  }
+
+  // Collapse any triple+ blank lines into double blank lines.
+  // This prevents ugly whitespace gaps where the A2A section used to be.
+  cleaned = cleaned.replace(/\n{3,}/g, '\n\n');
+
+  // Edge case: CLAUDE.md becomes empty after A2A section removal.
+  // If the only content was the A2A section, the file would be left as
+  // whitespace-only, which is confusing. Delete it entirely instead.
+  if (!cleaned.trim()) {
+    fs.rmSync(filePath, { force: true });
+    return 'deleted';
+  }
+
+  // Write the cleaned content back, ensuring the file ends with a newline
+  fs.writeFileSync(filePath, cleaned.trimEnd() + '\n');
+  return 'trimmed';
+}
+
+/**
+ * cleanupEmptyDir — removes a directory if it exists and contains no files.
+ *
+ * After removing A2A skill files, directories like .claude/commands/ may be
+ * empty. We remove them to avoid clutter, but ONLY if no user files remain.
+ * This prevents accidentally deleting directories that contain the user's
+ * own Claude Code commands or settings.
+ */
+function cleanupEmptyDir(dirPath, result) {
+  try {
+    if (!fs.existsSync(dirPath)) return;
+
+    // Check if directory stat confirms it's actually a directory
+    const stat = fs.statSync(dirPath);
+    if (!stat.isDirectory()) return;
+
+    const entries = fs.readdirSync(dirPath);
+
+    // Only remove if the directory is completely empty.
+    // Any remaining files (user's own commands, .gitkeep, etc.) mean we keep it.
+    if (entries.length === 0) {
+      fs.rmdirSync(dirPath);
+      result.removed.push(dirPath.split(path.sep).slice(-2).join('/') + '/ (empty directory)');
+    }
+  } catch (err) {
+    // Directory cleanup is best-effort. Failures here are non-fatal —
+    // an empty directory is harmless, just slightly untidy.
+  }
+}
+
+module.exports = { cleanupProjectFiles };

package/scripts/install-skills.js

@@ -1,13 +1,23 @@
 /**
  * A2A Skill Installer
  *
- * Copies Claude Code commands, CLAUDE.md context, and Codex AGENTS.md into a
- * target project directory. Idempotent: skips files that already exist with
- * identical content.
+ * Copies Claude Code commands, CLAUDE.md context, SKILL.md reference, and
+ * Codex AGENTS.md into a target project directory. Idempotent: skips files
+ * that already exist with identical content.
  *
  * CLAUDE.md is the key file — Claude Code reads it automatically, giving the
  * agent full context about the a2a CLI, native app, and onboarding flow
  * immediately after npm install.
+ *
+ * SKILL.md is the deep reference for A2A — invite formatting templates,
+ * incoming call handling, disclosure manifest flow, and protocol details.
+ * We copy it to .claude/ so Claude Code can discover it naturally without
+ * having to grep through node_modules. The .claude/ directory is already
+ * used for slash commands, so this is a natural home for reference docs.
+ *
+ * Unlike CLAUDE.md (which is auto-loaded), the skill reference file is only
+ * read when the agent explicitly looks in .claude/ — so it serves as opt-in
+ * deep reference rather than always-loaded context (avoiding token bloat).
  */
 
 const fs = require('fs');
@@ -15,9 +25,18 @@ const path = require('path');
 
 const PACKAGE_ROOT = path.join(__dirname, '..');
 
+// Section delimiter used to bound the A2A block inside CLAUDE.md.
+// This allows safe replacement of ONLY the A2A content when updating,
+// preserving any user content before or after the A2A section.
+const A2A_SECTION_END_MARKER = '<!-- END A2A CALLING SECTION -->';
+
 const SKILL_FILES = [
   // CLAUDE.md — gives Claude Code instant context about the a2a CLI
   { src: 'CLAUDE-INSTALL.md', dest: 'CLAUDE.md', mergeKey: '# A2A Calling' },
+  // SKILL.md — deep reference for A2A (invite formatting, call handling, etc.)
+  // Copied to .claude/ so Claude Code discovers it naturally without grepping
+  // node_modules. This is opt-in context: only loaded when the agent looks.
+  { src: 'SKILL.md', dest: '.claude/a2a-skill-reference.md' },
   // Claude Code slash commands
   { src: '.claude/commands/a2a-call.md', dest: '.claude/commands/a2a-call.md' },
   { src: '.claude/commands/a2a-invite.md', dest: '.claude/commands/a2a-invite.md' },
@@ -31,6 +50,20 @@ const SKILL_FILES = [
 function installSkills(targetDir, options = {}) {
   const result = { installed: [], skipped: [], errors: [] };
 
+  // Install manifest: .a2a-manifest.json
+  //
+  // After installing skill files, we write a manifest recording every file
+  // we touched, what action was taken, and the package version. This serves
+  // three purposes:
+  //   1. Transparency — user can see exactly what the package added
+  //   2. Clean uninstall — `a2a uninstall` reads the manifest to remove files
+  //   3. Upgrade tracking — on re-install, we can compare versions and
+  //      only update files that actually changed
+  //
+  // The manifest is written to the project root (same level as CLAUDE.md)
+  // so it's easy to find.
+  const manifestEntries = [];
+
   for (const file of SKILL_FILES) {
     const srcPath = path.join(PACKAGE_ROOT, file.src);
     const destPath = path.join(targetDir, file.dest);
@@ -38,6 +71,7 @@ function installSkills(targetDir, options = {}) {
     try {
       if (!fs.existsSync(srcPath)) {
         result.errors.push({ file: file.src, error: 'Source file not found' });
+        manifestEntries.push({ path: file.dest, action: 'error', detail: 'Source file not found' });
         continue;
       }
 
@@ -46,47 +80,125 @@ function installSkills(targetDir, options = {}) {
       if (fs.existsSync(destPath)) {
         const existing = fs.readFileSync(destPath, 'utf8');
 
-        // Merge mode: if the file has a mergeKey, append/replace the A2A section
-        // in an existing file rather than overwriting it entirely.
+        // ── CLAUDE.md merge strategy ──────────────────────────────────────
+        //
+        // The a2acalling package installs context into the project's CLAUDE.md so
+        // Claude Code has immediate awareness of the CLI, commands, and native app.
+        // But projects often have their own CLAUDE.md with project-specific instructions.
+        //
+        // To avoid clobbering user content, we use a section-delimited merge:
+        //   1. If CLAUDE.md doesn't exist: write CLAUDE-INSTALL.md as-is
+        //   2. If CLAUDE.md exists WITHOUT an A2A section: append at the end
+        //   3. If CLAUDE.md exists WITH an A2A section: replace only between
+        //      "# A2A Calling" and "<!-- END A2A CALLING SECTION -->"
+        //
+        // The end marker ensures user content after the A2A block is preserved.
+        // Legacy installs without the marker fall back to replace-to-EOF (old behavior)
+        // but the marker is added during the update so future updates are safe.
         if (file.mergeKey) {
           if (existing.includes(file.mergeKey)) {
-            // A2A section already present — extract and compare
+            // A2A section already present — find its boundaries
             const sectionStart = existing.indexOf(file.mergeKey);
-            const existingSection = existing.slice(sectionStart);
+
+            // Check if the end marker exists to determine section boundaries.
+            // If found, we only replace the bounded section, preserving any
+            // user content after the marker. If not found (legacy installs
+            // that predate the marker), we replace from the header to EOF
+            // and add the marker so future updates are safe.
+            const endMarkerIndex = existing.indexOf(A2A_SECTION_END_MARKER, sectionStart);
+
+            let existingSection;
+            let after = '';
+
+            if (endMarkerIndex !== -1) {
+              // End marker found — extract only the bounded A2A section
+              const sectionEnd = endMarkerIndex + A2A_SECTION_END_MARKER.length;
+              existingSection = existing.slice(sectionStart, sectionEnd);
+              // Preserve everything after the end marker (user's trailing content)
+              after = existing.slice(sectionEnd);
+            } else {
+              // Legacy install without end marker — take everything from header to EOF
+              // The new content includes the marker, so future updates will be safe
+              existingSection = existing.slice(sectionStart);
+            }
+
+            // Compare the existing A2A section with the new source content.
+            // Skip the update if they're identical (idempotent behavior).
             if (!options.force && existingSection.trim() === srcContent.trim()) {
               result.skipped.push(file.dest);
+              manifestEntries.push({ path: file.dest, action: 'skipped' });
               continue;
             }
-            // Replace the A2A section with updated content
+
+            // Replace only the A2A section, preserving content before and after
             const before = existing.slice(0, sectionStart).trimEnd();
-            const merged = before ? before + '\n\n' + srcContent : srcContent;
+            let merged = before ? before + '\n\n' + srcContent : srcContent;
+            // Re-attach any trailing content that was after the end marker
+            if (after) {
+              merged = merged.trimEnd() + '\n' + after;
+            }
             fs.writeFileSync(destPath, merged);
             result.installed.push(file.dest + ' (updated A2A section)');
+            manifestEntries.push({ path: file.dest, action: 'updated A2A section' });
           } else {
-            // Existing CLAUDE.md without A2A section — append
+            // Existing CLAUDE.md without A2A section — append at the end
             const merged = existing.trimEnd() + '\n\n' + srcContent;
             fs.writeFileSync(destPath, merged);
             result.installed.push(file.dest + ' (appended A2A section)');
+            manifestEntries.push({ path: file.dest, action: 'appended A2A section' });
           }
           continue;
         }
 
-        // Standard mode: skip if identical
+        // Standard mode: skip if identical (non-merge files)
         if (!options.force && existing === srcContent) {
           result.skipped.push(file.dest);
+          manifestEntries.push({ path: file.dest, action: 'skipped' });
           continue;
         }
+      } else {
+        // File doesn't exist yet — will be created below
       }
 
       // Create directory and write file
       fs.mkdirSync(path.dirname(destPath), { recursive: true });
       fs.writeFileSync(destPath, srcContent);
       result.installed.push(file.dest);
+      manifestEntries.push({ path: file.dest, action: 'created' });
     } catch (err) {
       result.errors.push({ file: file.dest, error: err.message });
+      manifestEntries.push({ path: file.dest, action: 'error', detail: err.message });
     }
   }
 
+  // ── Write install manifest ────────────────────────────────────────────
+  //
+  // The manifest records every file we touched so the user (or `a2a uninstall`)
+  // knows exactly what was installed. We include the manifest itself in the list
+  // for completeness.
+  try {
+    const pkg = require('../package.json');
+    const manifestPath = path.join(targetDir, '.a2a-manifest.json');
+
+    // Add the manifest file itself to the entries list
+    manifestEntries.push({ path: '.a2a-manifest.json', action: 'created' });
+    // Add the install log file (written by postinstall.js)
+    manifestEntries.push({ path: '.a2a-install.log', action: 'created' });
+
+    const manifest = {
+      version: pkg.version,
+      installed_at: new Date().toISOString(),
+      files: manifestEntries,
+    };
+
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  } catch (err) {
+    // Non-fatal — the manifest is a convenience for cleanup, not required
+    // for the skill files to work. Failure here (e.g., read-only dir)
+    // should not break the install.
+    result.errors.push({ file: '.a2a-manifest.json', error: err.message });
+  }
+
   return result;
 }
 

package/scripts/postinstall.js

@@ -23,6 +23,7 @@
 if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) process.exit(0);
 if (process.env.DOCKER) process.exit(0);
 
+const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { spawnSync } = require('child_process');
@@ -70,6 +71,22 @@ function printGettingStarted() {
   const isMac = os.platform() === 'darwin';
   const pkg = require('../package.json');
 
+  // ── Short critical stderr output ──────────────────────────────────────
+  //
+  // npm v7+ suppresses stdout/stderr from postinstall scripts unless
+  // --foreground-scripts is used. We print a minimal critical line to stderr
+  // (which npm sometimes still shows) AND write the full banner to a log file
+  // so that Claude Code or a human can always find the getting-started info.
+  const shortLines = [
+    `a2acalling v${pkg.version} installed.`,
+    'Next step: a2a quickstart',
+    'Skills installed: /a2a-setup, /a2a-call, /a2a-contacts, /a2a-invite, /a2a-status',
+  ];
+  // Print the short critical summary to stderr — this is the most likely
+  // output to survive npm's output suppression in v7+
+  console.error(shortLines.join('\n'));
+
+  // ── Full verbose banner ───────────────────────────────────────────────
   const lines = [
     '',
     '╔══════════════════════════════════════════════════════════════╗',
@@ -176,9 +193,32 @@ function printGettingStarted() {
     '',
   );
 
-  // Print to stderr — npm v7+ captures stdout from lifecycle scripts,
-  // but stderr is still visible in many agent contexts
-  console.error(lines.join('\n'));
-  // Also print to stdout for contexts where stderr is filtered
-  console.log(lines.join('\n'));
+  const fullBanner = lines.join('\n');
+
+  // Print the full banner to stdout for contexts where it's visible
+  // (e.g., --foreground-scripts, direct script execution, agent contexts)
+  console.log(fullBanner);
+
+  // ── Write full banner to a log file ─────────────────────────────────
+  //
+  // Even when npm suppresses terminal output, the agent or human can read
+  // this file to get the full getting-started info. We write to the project
+  // root (initCwd) so it's next to CLAUDE.md and easy to discover.
+  try {
+    const logPath = path.join(initCwd, '.a2a-install.log');
+    const logContent = [
+      `a2acalling v${pkg.version} — install summary`,
+      `Installed at: ${new Date().toISOString()}`,
+      `Target directory: ${initCwd}`,
+      `Global install: ${isGlobal}`,
+      '',
+      ...shortLines,
+      '',
+      fullBanner,
+    ].join('\n');
+    fs.writeFileSync(logPath, logContent);
+  } catch (e) {
+    // Non-fatal — the log file is a convenience, not a requirement.
+    // This can fail if the target directory is read-only (e.g., system dirs).
+  }
 }

package/scripts/preuninstall.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+// ============================================================================
+// npm preuninstall hook — manifest-driven cleanup
+//
+// When `npm uninstall a2acalling` runs, npm calls this script BEFORE
+// removing the package from node_modules. We read .a2a-manifest.json
+// to find every file our postinstall created and remove them cleanly.
+//
+// CLAUDE.md gets special handling: we only remove the A2A section
+// (between "# A2A Calling" and "<!-- END A2A CALLING SECTION -->"),
+// preserving any project-specific content the user added before/after.
+//
+// If the manifest doesn't exist (manual install, old version), we
+// skip cleanup gracefully — better to leave files than crash the uninstall.
+// ============================================================================
+
+// Skip in CI environments — cleanup is not needed in ephemeral containers
+if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) process.exit(0);
+if (process.env.DOCKER) process.exit(0);
+
+try {
+  const path = require('path');
+  const { cleanupProjectFiles } = require('./cleanup');
+
+  // INIT_CWD is set by npm to the directory where `npm uninstall` was run.
+  // This is the project root where postinstall placed the skill files.
+  // Falls back to cwd() which should also be the project root during npm lifecycle.
+  const targetDir = process.env.INIT_CWD || process.cwd();
+
+  const result = cleanupProjectFiles(targetDir);
+
+  // Print a short summary so the user (or agent) knows what was cleaned up.
+  // This output may be suppressed by npm v7+ unless --foreground-scripts is used,
+  // but it's still useful for debugging and for agents that capture stderr.
+  if (result.removed.length > 0) {
+    console.error(`a2acalling: cleaned up ${result.removed.length} file(s):`);
+    for (const f of result.removed) {
+      console.error(`  - ${f}`);
+    }
+  }
+  if (result.preserved.length > 0) {
+    for (const f of result.preserved) {
+      console.error(`  ~ ${f}`);
+    }
+  }
+  if (result.errors.length > 0) {
+    console.error(`  Warnings (${result.errors.length}):`);
+    for (const e of result.errors) {
+      console.error(`  ! ${e}`);
+    }
+  }
+  if (result.removed.length === 0 && result.preserved.length === 0 && result.errors.length === 0) {
+    // No manifest found or manifest was empty — nothing to clean up.
+    // This is expected for fresh installs that never ran postinstall,
+    // or for projects where cleanup was already done via `a2a uninstall`.
+    console.error('a2acalling: no install manifest found, skipping project cleanup.');
+    console.error('  Tip: run `a2a uninstall` to also remove server config and database.');
+  }
+} catch (err) {
+  // CRITICAL: Never crash the npm uninstall process.
+  // If our cleanup fails for any reason, npm should still be able to remove
+  // the package from node_modules. A failed cleanup leaves orphaned files,
+  // which is annoying but not harmful. A crashed uninstall is much worse.
+  console.error(`a2acalling: cleanup warning — ${err.message}`);
+}
+
+process.exit(0);