kushi-agents 4.3.0 → 4.4.0

package/plugin/templates/init/rsi-program-catalog.template.json

@@ -0,0 +1,107 @@
+{
+  "rsiProgramCatalog": {
+    "version": "2026-05-08",
+    "description": "Committed RSI program-name reference catalog for HLS-related classification during 6Q and report authoring.",
+    "classificationGuidance": {
+      "directMatch": "Use when the ask clearly aligns to one or more catalog program names.",
+      "remoteChance": "Use when the ask has only a weak or partial overlap and should be labeled as a remote chance rather than a direct fit.",
+      "none": "If no plausible direct or remote-chance program match exists, mark the classification as None."
+    },
+    "segments": [
+      {
+        "segment": "HLS MedTech",
+        "programNames": [
+          "RSI | [HLS MedTech] AI factory digital twins",
+          "RSI | [HLS MedTech] AI-enabled guided selling and customer service",
+          "RSI | [HLS MedTech] Augmented device research with optimized data & AI",
+          "RSI | [HLS MedTech] Care experience personalization through connected devices",
+          "RSI | [HLS MedTech] Connected Devices",
+          "RSI | [HLS MedTech] Emerging Use Case",
+          "RSI | [HLS MedTech] MedTech Sales and Field Service",
+          "RSI | [HLS MedTech] Optimized Supply chain Augmented end to end supply chain management",
+          "RSI | [HLS MedTech] Oracle Database on Azure",
+          "RSI | [HLS MedTech] SAP on Azure",
+          "RSI | [HLS MedTech] Unified Threat and Identity Protection"
+        ]
+      },
+      {
+        "segment": "HLS Payor",
+        "programNames": [
+          "RSI | [HLS Payor] Accelerate claims administration, prior authorization, billing, and enrollment processes through automation",
+          "RSI | [HLS Payor] AI-Powered Contact Center",
+          "RSI | [HLS Payor] Care Management",
+          "RSI | [HLS Payor] Core Operations Modernization",
+          "RSI | [HLS Payor] Defend against ransomware and breaches",
+          "RSI | [HLS Payor] Differentiate with integrated and AI-powered cybersecurity",
+          "RSI | [HLS Payor] Digital Clinical Quality Measures",
+          "RSI | [HLS Payor] Emerging Use Case",
+          "RSI | [HLS Payor] Enhance team communication and collaboration across all functional areas (clinical/non-clinical)",
+          "RSI | [HLS Payor] Interoperability Platforms",
+          "RSI | [HLS Payor] M365 Copilot for Payors",
+          "RSI | [HLS Payor] Personalize the Member Experience",
+          "RSI | [HLS Payor] Prior Authorization",
+          "RSI | [HLS Payor] Protect identities and access",
+          "RSI | [HLS Payor] Revenue Cycle Management",
+          "RSI | [HLS Payor] TriZetto on Azure",
+          "RSI | [HLS Payor] Unify member, provider, and clinical data to enhance member outcomes and drive operational efficiency"
+        ]
+      },
+      {
+        "segment": "HLS Pharma",
+        "programNames": [
+          "RSI | [HLS Pharma] Agentic Trials Execution",
+          "RSI | [HLS Pharma] AI factory digital twins",
+          "RSI | [HLS Pharma] AI-enabled guided selling and customer service",
+          "RSI | [HLS Pharma] Augmented end to end supply chain management",
+          "RSI | [HLS Pharma] Augmented research and drug discovery with optimized data and AI",
+          "RSI | [HLS Pharma] Clinical Trials Matching",
+          "RSI | [HLS Pharma] Custom Sales Agent",
+          "RSI | [HLS Pharma] Emerging Use Case",
+          "RSI | [HLS Pharma] Lab Automation",
+          "RSI | [HLS Pharma] Optimized Supply chain",
+          "RSI | [HLS Pharma] Oracle Database on Azure",
+          "RSI | [HLS Pharma] Pharmacovigilance & Drug Safety",
+          "RSI | [HLS Pharma] Real-World Evidence",
+          "RSI | [HLS Pharma] Regulated Documents Generation",
+          "RSI | [HLS Pharma] SAP on Azure",
+          "RSI | [HLS Pharma] Scientific Data Mining and Sharing",
+          "RSI | [HLS Pharma] Scientific Workflow Automation (MSFT Discovery)",
+          "RSI | [HLS Pharma] Streamlined clinical trial development & submission",
+          "RSI | [HLS Pharma] Study Protocols",
+          "RSI | [HLS Pharma] Trusted Research Environment",
+          "RSI | [HLS Pharma] Unified Threat and Identity Protection"
+        ]
+      },
+      {
+        "segment": "HLS Provider",
+        "programNames": [
+          "RSI | [HLS Provider] Accelerate clinical research and patient care",
+          "RSI | [HLS Provider] AI Transformation: Smart Hospitals / Hospital of the Future (including Digital Twin)",
+          "RSI | [HLS Provider] Defend against ransomware, breaches, isolated protection",
+          "RSI | [HLS Provider] Differentiate with integrated and AI-powered cybersecurity",
+          "RSI | [HLS Provider] EHR on Azure: Cloud Migration",
+          "RSI | [HLS Provider] EHR on Azure: Developer and testing training environment",
+          "RSI | [HLS Provider] EHR on Azure: Isolated protection against ransomware attacks",
+          "RSI | [HLS Provider] EHR on Azure: Optimize Operations and Data Insights",
+          "RSI | [HLS Provider] Emerging Use Case",
+          "RSI | [HLS Provider] Enhance care management with actionable insights",
+          "RSI | [HLS Provider] Enhance care team communication and collaboration",
+          "RSI | [HLS Provider] Imaging: Accelerate radiology report creation and the discovery of medical insights",
+          "RSI | [HLS Provider] Imaging: Cloud Migration",
+          "RSI | [HLS Provider] Imaging: Transform image sharing and patient care coordination",
+          "RSI | [HLS Provider] Population Health Platforms",
+          "RSI | [HLS Provider] Protecting identities and access",
+          "RSI | [HLS Provider] Streamline clinical documentation and workflows (Dragon)",
+          "RSI | [HLS Provider] Trusted Research Environment"
+        ]
+      },
+      {
+        "segment": "HLS Cross-Segment",
+        "programNames": [
+          "RSI | [HLS] Personalize patient engagement",
+          "RSI | [HLS] Emerging Use Case"
+        ]
+      }
+    ]
+  }
+}

package/src/config-loader.mjs

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Node-side twin of Get-KushiConfig.ps1.
+ *
+ * Lookup order:
+ *   1. <workspace>/.kushi/config/user/<name>.<ext>
+ *   2. <workspace>/.kushi/config/shared/<name>.<ext>
+ *
+ * @param {string} name          Logical config name (e.g. 'm365-auth', 'project-evidence').
+ * @param {object} [opts]
+ * @param {string} [opts.workspace=process.cwd()] Workspace root.
+ * @param {string} [opts.ext]    Override extension (json | yml | yaml).
+ * @param {boolean} [opts.raw=false] Return raw text instead of parsed object.
+ * @param {boolean} [opts.pathOnly=false] Return only the resolved file path.
+ * @param {boolean} [opts.allowPlaceholders=false] Skip __FILL_ME_IN__/<auto> check.
+ * @returns {string|object} Parsed object (or raw text, or path).
+ */
+export function loadKushiConfig(name, opts = {}) {
+  const workspace = opts.workspace || process.cwd();
+  const ext = opts.ext || defaultExt(name);
+  const fileName = `${name}.${ext}`;
+
+  const configRoot = path.join(workspace, '.kushi', 'config');
+  const userPath = path.join(configRoot, 'user', fileName);
+  const sharedPath = path.join(configRoot, 'shared', fileName);
+
+  let resolved = null;
+  if (fs.existsSync(userPath)) resolved = userPath;
+  else if (fs.existsSync(sharedPath)) resolved = sharedPath;
+
+  if (!resolved) {
+    throw new Error(
+      `Kushi config '${name}' not found. Looked in:\n` +
+      `  - ${userPath}\n` +
+      `  - ${sharedPath}\n` +
+      `Run \`npx kushi-agents@latest\` to (re)seed config files.`
+    );
+  }
+
+  if (opts.pathOnly) return resolved;
+
+  const raw = fs.readFileSync(resolved, 'utf8');
+
+  if (!opts.allowPlaceholders) {
+    if (raw.includes('__FILL_ME_IN__') || raw.includes('<auto>')) {
+      throw new Error(
+        `Kushi config '${resolved}' still has template placeholders. ` +
+        `Edit it with real values, or pass {allowPlaceholders: true}.`
+      );
+    }
+  }
+
+  if (opts.raw) return raw;
+  if (ext === 'json') return JSON.parse(raw);
+  // YAML: return raw — Node has no built-in parser. Caller installs js-yaml if needed.
+  return raw;
+}
+
+function defaultExt(name) {
+  if (/^(project-evidence|integrations)$/.test(name)) return 'yml';
+  return 'json';
+}
+
+/** Resolve path only — convenience wrapper. */
+export function resolveKushiConfigPath(name, opts = {}) {
+  return loadKushiConfig(name, { ...opts, pathOnly: true });
+}

package/src/constants.mjs

@@ -20,21 +20,69 @@ export const CLAWPILOT_SKILL_DEST = 'SKILL.md';
 export const PLUGIN_SOURCE_DIR = 'plugin';
 
 /** Asset subdirectories under plugin/ that get copied. */
-export const ASSET_DIRS = ['agents', 'instructions', 'prompts', 'skills', 'templates', 'reference-packs'];
+export const ASSET_DIRS = ['agents', 'instructions', 'prompts', 'skills', 'templates', 'reference-packs', 'lib'];
 
 /**
  * User-editable config directory under the install destination.
- * Seeded on first install only; never overwritten on reinstall / --force / upgrade.
+ *
+ * v4.4.0 introduces a two-tier split inside config/:
+ *   - shared/  → team-owned, safe to commit. Doctrine + team defaults.
+ *   - user/    → per-contributor identity & local paths. Gitignored.
+ *
+ * Skills read configs via the Get-KushiConfig helper which checks
+ * user/ first, then shared/.
  */
 export const CONFIG_DIR = 'config';
+export const CONFIG_SHARED_SUBDIR = 'shared';
+export const CONFIG_USER_SUBDIR = 'user';
 
 /**
- * Files seeded into <dest>/config/ on first install only.
- * Each entry: { template: <path under plugin/templates/init/>, target: <name in config/> }
+ * Per-contributor config files (USER tier).
+ * Seeded only if absent; preserved on reinstall/upgrade.
+ * Written to <dest>/config/user/. Gitignored by installer.
  */
-export const CONFIG_SEED_FILES = [
+export const CONFIG_USER_SEED_FILES = [
   { template: 'init/project-evidence.template.yml', target: 'project-evidence.yml' },
-  { template: 'init/integrations.template.yml',     target: 'integrations.yml'     },
+  { template: 'init/m365-auth.template.json',       target: 'm365-auth.json'       },
+  { template: 'init/m365-mutable.template.json',    target: 'm365-mutable.json'    },
+];
+
+/**
+ * Team-shared config files (SHARED tier, seed-once).
+ * Seeded only if absent; preserved on reinstall.
+ * Written to <dest>/config/shared/. Safe to commit.
+ */
+export const CONFIG_SHARED_SEED_FILES = [
+  { template: 'init/integrations.template.yml', target: 'integrations.yml' },
+];
+
+/**
+ * Doctrine config files (SHARED tier, overwrite-always).
+ * Versioned by Kushi; overwritten on every install. User hand-edits are lost.
+ * Written to <dest>/config/shared/.
+ */
+export const CONFIG_DOCTRINE_FILES = [
+  { template: 'init/azuredevops.template.json',         target: 'azuredevops.json'         },
+  { template: 'init/dynamics365.template.json',         target: 'dynamics365.json'         },
+  { template: 'init/rsi-program-catalog.template.json', target: 'rsi-program-catalog.json' },
+];
+
+/**
+ * Example/reference scaffolds (SHARED tier, overwrite-always).
+ * Written to <dest>/config/shared/.
+ */
+export const CONFIG_EXAMPLE_FILES = [
+  { template: 'init/m365-auth.example.json',    target: 'm365-auth.json.example'    },
+  { template: 'init/m365-mutable.example.json', target: 'm365-mutable.json.example' },
+];
+
+/**
+ * Lines written to <dest>/.gitignore (created if missing, appended otherwise).
+ * Marks the per-user tier so contributors don't accidentally commit identity/paths.
+ */
+export const CONFIG_GITIGNORE_LINES = [
+  '# Kushi per-user config — never commit (created by kushi-agents installer)',
+  'config/user/',
 ];
 
 /** Files to exclude from consumer installs (relative to plugin/). */
@@ -43,18 +91,6 @@ export const EXCLUDED_FILES = [];
 /** Directories to exclude from consumer installs (relative to plugin/). */
 export const EXCLUDED_DIRS = [];
 
-/** Files copied to the TARGET project's .github/ directory. */
-export const PROJECT_GITHUB_FILES = [];
-
-/** Directories copied to the TARGET project's .github/ directory. */
-export const PROJECT_GITHUB_DIRS = ['config'];
-
-/** Project-level .github files that must never be copied into consumer projects. */
-export const PROJECT_GITHUB_EXCLUDED_FILES = [
-  'config/m365-auth.json',
-  'config/m365-mutable.json'
-];
-
 /**
  * Files / directories that indicate the cwd is a sane install target.
  *

package/src/copy-assets.mjs

@@ -5,9 +5,6 @@ import {
   EXCLUDED_FILES,
   EXCLUDED_DIRS,
   PLUGIN_SOURCE_DIR,
-  PROJECT_GITHUB_FILES,
-  PROJECT_GITHUB_DIRS,
-  PROJECT_GITHUB_EXCLUDED_FILES,
 } from './constants.mjs';
 
 /**
@@ -97,31 +94,6 @@ function copyDirFiltered(src, dest, assetDir, relPrefix = '', includeFilter) {
  * @param {string} projectDir
  * @param {string} [relPrefix='']
  */
-function copyProjectDirFiltered(src, dest, projectDir, relPrefix = '') {
-  fs.mkdirSync(dest, { recursive: true });
-
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
-    const excludeKey = `${projectDir}/${relPath}`;
-
-    if (entry.isDirectory()) {
-      copyProjectDirFiltered(srcPath, destPath, projectDir, relPrefix ? `${relPrefix}/${entry.name}` : entry.name);
-      continue;
-    }
-
-    if (PROJECT_GITHUB_EXCLUDED_FILES.includes(excludeKey)) continue;
-
-    fs.cpSync(srcPath, destPath, { force: true });
-  }
-}
-
-/**
- * Count files recursively in a directory.
- * @param {string} dir
- * @returns {number}
- */
 function countFiles(dir) {
   let count = 0;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -133,51 +105,3 @@ function countFiles(dir) {
   }
   return count;
 }
-
-/**
- * Copy project-level files (hooks, copilot-instructions) to the target
- * project's .github/ directory. Does not overwrite existing files.
- *
- * @param {string} sourcePkgDir – root of the npm package
- * @returns {{ copied: string[], skipped: string[] }}
- */
-export function copyProjectFiles(sourcePkgDir) {
-  const projectGitHub = path.join(process.cwd(), '.github');
-  const srcGitHub = path.join(sourcePkgDir, '.github');
-
-  const copied = [];
-  const skipped = [];
-
-  for (const file of PROJECT_GITHUB_FILES) {
-    const src = path.join(srcGitHub, file);
-    const dest = path.join(projectGitHub, file);
-
-    if (!fs.existsSync(src)) continue;
-
-    if (fs.existsSync(dest)) {
-      skipped.push(`.github/${file}`);
-      continue;
-    }
-
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.cpSync(src, dest);
-    copied.push(`.github/${file}`);
-  }
-
-  for (const dir of PROJECT_GITHUB_DIRS) {
-    const src = path.join(srcGitHub, dir);
-    const dest = path.join(projectGitHub, dir);
-
-    if (!fs.existsSync(src)) continue;
-
-    if (fs.existsSync(dest)) {
-      skipped.push(`.github/${dir}/`);
-      continue;
-    }
-
-    copyProjectDirFiltered(src, dest, dir);
-    copied.push(`.github/${dir}/`);
-  }
-
-  return { copied, skipped };
-}

package/src/main.mjs

@@ -13,7 +13,7 @@ import {
   PROJECT_MARKERS,
 } from './constants.mjs';
 import { promptForDestination } from './prompt.mjs';
-import { copyAssets, copyProjectFiles } from './copy-assets.mjs';
+import { copyAssets } from './copy-assets.mjs';
 import { mergeSettings } from './settings.mjs';
 import { mergeCopilotInstructions } from './copilot-instructions.mjs';
 import { seedConfig } from './seed-config.mjs';
@@ -134,12 +134,8 @@ async function installVscode(options, resolved, version) {
   const manifestPath = writeInstalledManifest(fullDest, resolved, version);
   console.log(`    - kushi-install.json (profile manifest)`);
 
-  const { seeded, preserved } = seedConfig(PKG_ROOT, fullDest);
-  if (seeded.length > 0 || preserved.length > 0) {
-    console.log(`\n  Config (.kushi/config/ — user-editable, preserved across upgrades):`);
-    for (const f of seeded)    console.log(`    - ${f} -> seeded from template`);
-    for (const f of preserved) console.log(`    - ${f} -> preserved (already exists)`);
-  }
+  const seedRes = seedConfig(PKG_ROOT, fullDest);
+  printSeedReport(seedRes, `${dest}/`);
 
   if (!options.noSettings) {
     const { created, keysAdded, keysUnchanged } = mergeSettings(
@@ -176,19 +172,6 @@ async function installVscode(options, resolved, version) {
     console.log('\n  Skipped .github/copilot-instructions.md (--no-instructions)');
   }
 
-  const { copied: projCopied, skipped: projSkipped } = copyProjectFiles(PKG_ROOT);
-  if (projCopied.length > 0) {
-    console.log('\n  Copied project files to .github/');
-    for (const f of projCopied) {
-      console.log(`    - ${f}`);
-    }
-  }
-  if (projSkipped.length > 0) {
-    for (const f of projSkipped) {
-      console.log(`    - ${f} -> unchanged (already exists)`);
-    }
-  }
-
   printPostInstall(resolved, '@Kushi');
 }
 
@@ -233,12 +216,8 @@ async function installClawpilot(options, resolved, version) {
   writeInstalledManifest(fullDest, resolved, version);
   console.log(`    - kushi-install.json (profile manifest)`);
 
-  const { seeded, preserved } = seedConfig(PKG_ROOT, fullDest);
-  if (seeded.length > 0 || preserved.length > 0) {
-    console.log(`\n  Config (${displayDest}\\config\\ — user-editable, preserved across upgrades):`);
-    for (const f of seeded)    console.log(`    - ${f} -> seeded from template`);
-    for (const f of preserved) console.log(`    - ${f} -> preserved (already exists)`);
-  }
+  const seedRes = seedConfig(PKG_ROOT, fullDest);
+  printSeedReport(seedRes, `${displayDest}\\`);
 
   // Mirror agents/kushi.agent.md as top-level SKILL.md for Clawpilot discovery.
   const agentSrc = path.join(PKG_ROOT, PLUGIN_SOURCE_DIR, CLAWPILOT_AGENT_SOURCE);
@@ -253,6 +232,31 @@ async function installClawpilot(options, resolved, version) {
   printPostInstall(resolved, 'kushi');
 }
 
+function printSeedReport(r, dispDestSlash) {
+  const total =
+    r.seededUser.length + r.seededShared.length +
+    r.preservedUser.length + r.preservedShared.length +
+    r.doctrine.length + r.examples.length;
+  if (total === 0 && r.gitignore === 'unchanged') return;
+
+  console.log(`\n  Config (${dispDestSlash}config/):`);
+  if (r.seededShared.length || r.preservedShared.length || r.doctrine.length || r.examples.length) {
+    console.log(`    shared/  (team-owned, safe to commit)`);
+    for (const f of r.seededShared)    console.log(`      - ${f} -> seeded (team default; preserved on reinstall)`);
+    for (const f of r.preservedShared) console.log(`      - ${f} -> preserved (already exists)`);
+    for (const f of r.doctrine)        console.log(`      - ${f} -> updated (Kushi-versioned doctrine; do not hand-edit)`);
+    for (const f of r.examples)        console.log(`      - ${f} -> refreshed (reference scaffold)`);
+  }
+  if (r.seededUser.length || r.preservedUser.length) {
+    console.log(`    user/    (per-contributor; gitignored)`);
+    for (const f of r.seededUser)    console.log(`      - ${f} -> seeded (edit before first bootstrap)`);
+    for (const f of r.preservedUser) console.log(`      - ${f} -> preserved (already exists)`);
+  }
+  if (r.gitignore === 'created' || r.gitignore === 'appended') {
+    console.log(`    .gitignore ${r.gitignore === 'created' ? 'created' : 'appended'} -> config/user/ excluded`);
+  }
+}
+
 function printPostInstall(resolved, prefix) {
   console.log(`\n  Done. Profile "${resolved.profile}" installed. Available verbs:`);
   for (const verb of resolved.verbs) {

package/src/seed-config.mjs

@@ -2,43 +2,108 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {
   CONFIG_DIR,
-  CONFIG_SEED_FILES,
+  CONFIG_SHARED_SUBDIR,
+  CONFIG_USER_SUBDIR,
+  CONFIG_USER_SEED_FILES,
+  CONFIG_SHARED_SEED_FILES,
+  CONFIG_DOCTRINE_FILES,
+  CONFIG_EXAMPLE_FILES,
+  CONFIG_GITIGNORE_LINES,
   PLUGIN_SOURCE_DIR,
 } from './constants.mjs';
 
 /**
- * Seed <dest>/config/ with user-editable config files on FIRST INSTALL ONLY.
+ * Seed <dest>/config/ with config files using a two-tier shared/ + user/ layout.
  *
- * Rules:
- *   - If <dest>/config/<file> already exists → skip (never overwrite).
- *   - Behavior is identical regardless of --force; config/ is user territory.
- *   - Returns a per-file result so the installer can summarize what happened.
+ *   <dest>/config/
+ *     shared/   ← team-owned, safe to commit (doctrine + team defaults + .example scaffolds)
+ *     user/     ← per-contributor identity & local paths (gitignored)
+ *
+ * Policies:
+ *   - USER SEED (user/, seed-once): copied only if absent. Preserved on reinstall.
+ *   - SHARED SEED (shared/, seed-once): copied only if absent. Preserved on reinstall.
+ *   - DOCTRINE (shared/, overwrite-always): always rewritten — Kushi-versioned.
+ *   - EXAMPLES (shared/, overwrite-always): always rewritten — reference scaffolds.
+ *
+ * Also writes <dest>/.gitignore with `config/user/` to prevent accidental commits.
  *
  * @param {string} sourcePkgDir – root of the npm package
  * @param {string} destAbsolute – absolute install destination (e.g. <workspace>/.kushi)
- * @returns {{ seeded: string[], preserved: string[] }}
+ * @returns {{
+ *   seededUser: string[],     // user/ files freshly created
+ *   seededShared: string[],   // shared/ seed-once files freshly created
+ *   preservedUser: string[],  // user/ files left untouched (already existed)
+ *   preservedShared: string[],// shared/ seed-once files left untouched
+ *   doctrine: string[],       // shared/ doctrine files written (always)
+ *   examples: string[],       // shared/ .example files written (always)
+ *   gitignore: 'created' | 'appended' | 'unchanged' | 'skipped',
+ * }}
  */
 export function seedConfig(sourcePkgDir, destAbsolute) {
-  const configDir = path.join(destAbsolute, CONFIG_DIR);
-  fs.mkdirSync(configDir, { recursive: true });
-
-  const seeded = [];
-  const preserved = [];
+  const sharedDir = path.join(destAbsolute, CONFIG_DIR, CONFIG_SHARED_SUBDIR);
+  const userDir = path.join(destAbsolute, CONFIG_DIR, CONFIG_USER_SUBDIR);
+  fs.mkdirSync(sharedDir, { recursive: true });
+  fs.mkdirSync(userDir, { recursive: true });
 
-  for (const { template, target } of CONFIG_SEED_FILES) {
-    const src = path.join(sourcePkgDir, PLUGIN_SOURCE_DIR, 'templates', template);
-    const dst = path.join(configDir, target);
+  const result = {
+    seededUser: [],
+    seededShared: [],
+    preservedUser: [],
+    preservedShared: [],
+    doctrine: [],
+    examples: [],
+    gitignore: 'unchanged',
+  };
 
-    if (!fs.existsSync(src)) continue;
+  const seedOnce = (specs, destDir, seededList, preservedList) => {
+    for (const { template, target } of specs) {
+      const src = path.join(sourcePkgDir, PLUGIN_SOURCE_DIR, 'templates', template);
+      const dst = path.join(destDir, target);
+      if (!fs.existsSync(src)) continue;
+      if (fs.existsSync(dst)) {
+        preservedList.push(target);
+        continue;
+      }
+      fs.cpSync(src, dst);
+      seededList.push(target);
+    }
+  };
 
-    if (fs.existsSync(dst)) {
-      preserved.push(target);
-      continue;
+  const overwriteAlways = (specs, destDir, list) => {
+    for (const { template, target } of specs) {
+      const src = path.join(sourcePkgDir, PLUGIN_SOURCE_DIR, 'templates', template);
+      const dst = path.join(destDir, target);
+      if (!fs.existsSync(src)) continue;
+      fs.cpSync(src, dst, { force: true });
+      list.push(target);
     }
+  };
 
-    fs.cpSync(src, dst);
-    seeded.push(target);
-  }
+  // user/ tier
+  seedOnce(CONFIG_USER_SEED_FILES, userDir, result.seededUser, result.preservedUser);
+  // shared/ tier
+  seedOnce(CONFIG_SHARED_SEED_FILES, sharedDir, result.seededShared, result.preservedShared);
+  overwriteAlways(CONFIG_DOCTRINE_FILES, sharedDir, result.doctrine);
+  overwriteAlways(CONFIG_EXAMPLE_FILES, sharedDir, result.examples);
 
-  return { seeded, preserved };
+  // .gitignore at <dest>/.gitignore — append our marker block if not already present
+  result.gitignore = ensureGitignore(destAbsolute, CONFIG_GITIGNORE_LINES);
+
+  return result;
+}
+
+function ensureGitignore(destAbsolute, lines) {
+  const target = path.join(destAbsolute, '.gitignore');
+  const marker = lines[0];
+  const block = lines.join('\n') + '\n';
+
+  if (!fs.existsSync(target)) {
+    fs.writeFileSync(target, block, 'utf8');
+    return 'created';
+  }
+  const existing = fs.readFileSync(target, 'utf8');
+  if (existing.includes(marker)) return 'unchanged';
+  const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+  fs.writeFileSync(target, existing + sep + block, 'utf8');
+  return 'appended';
 }