@devran-ai/kit 4.1.0 → 4.2.0

package/.agent/CheatSheet.md

@@ -1,6 +1,6 @@
 # Devran AI Kit — CheatSheet
 
-> **Version**: v4.1.0 | **Quick Reference** for all capabilities
+> **Version**: v4.2.0 | **Quick Reference** for all capabilities
 > **Session**: Start with `/status`, end with session-end checklist
 
 ---

package/.agent/commands/help.md

@@ -24,7 +24,7 @@ Your complete guide to the Devran AI Kit. Type `/help` for a quick overview, or
 
 ## Quick Overview
 
-**Devran AI Kit v4.1.0** — Trust-Grade AI Development Framework
+**Devran AI Kit v4.2.0** — Trust-Grade AI Development Framework
 
 | Category | Count | Description |
 |:---------|:------|:------------|

package/.agent/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "kitVersion": "4.1.0",
+  "kitVersion": "4.2.0",
   "lastAuditedAt": null,
   "description": "Devran AI Kit — Trust-Grade AI Development Framework",
   "repository": "https://github.com/devran-ai/kit",

package/README.md

@@ -1,6 +1,6 @@
 # Devran AI Kit
 
-[![Version](https://img.shields.io/badge/version-4.1.0-blue.svg)](https://github.com/devran-ai/kit)
+[![Version](https://img.shields.io/badge/version-4.2.0-blue.svg)](https://github.com/devran-ai/kit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Tests](https://img.shields.io/badge/tests-382%20passing-brightgreen.svg)](tests/)
 [![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
@@ -47,6 +47,17 @@ Creates a new project with `.agent/` pre-configured. Templates: `minimal`, `node
 npx @devran-ai/kit init
 ```
 
+## How It Works in Teams
+
+Devran AI Kit is **personal developer tooling** — like your IDE settings. `kit init` adds `.agent/` to `.gitignore` by default so it stays local.
+
+| Mode | Command | Behavior |
+|------|---------|----------|
+| Personal (default) | `kit init` | `.agent/` gitignored — local only |
+| Team (opt-in) | `kit init --shared` | `.agent/` committed — shared with team |
+
+Your project's `CLAUDE.md` remains the single source of truth. The kit enhances your personal workflow without affecting teammates. Anyone who wants it runs `npx @devran-ai/kit init`.
+
 ### Updating
 
 ```bash

package/bin/kit.js

@@ -93,6 +93,7 @@ ${colors.bright}Options:${colors.reset}
   --file <path>             CI log file for heal command
   --ide <name>              Generate config for single IDE (cursor|opencode|codex)
   --skip-ide                Skip IDE config generation
+  --shared                  Commit .agent/ to repo (team mode — skip .gitignore)
 
 ${colors.bright}Examples:${colors.reset}
   npx @devran-ai/kit init
@@ -247,7 +248,7 @@ function initCommand(options) {
 
   // Dynamic step counter — avoids hardcoded step strings
   const isForceWithBackup = backupPath !== null;
-  const totalSteps = isForceWithBackup ? 6 : 4;
+  const totalSteps = isForceWithBackup ? 7 : 5;
   let currentStep = isForceWithBackup ? 2 : 1;
 
   // C-3: Atomic copy via temp directory
@@ -327,6 +328,26 @@ function initCommand(options) {
   }
   currentStep++;
 
+  // Add .agent/ to .gitignore (unless --shared)
+  if (!options.shared) {
+    logStep(`${currentStep}/${totalSteps}`, 'Configuring .gitignore...');
+    try {
+      const { addToGitignore } = require('../lib/io');
+      const result = addToGitignore(targetDir);
+      if (result.added) {
+        log('   ✓ .agent/ added to .gitignore (local dev tooling)', 'green');
+      } else {
+        log('   ✓ .agent/ already in .gitignore', 'green');
+      }
+    } catch (err) {
+      log(`   ⚠️  Could not update .gitignore: ${err.message}`, 'yellow');
+    }
+  } else {
+    logStep(`${currentStep}/${totalSteps}`, 'Shared mode — .agent/ will be committed');
+    log('   ℹ .gitignore not modified (--shared flag)', 'cyan');
+  }
+  currentStep++;
+
   // Final message
   logStep(`${currentStep}/${totalSteps}`, 'Setup complete!');
   
@@ -683,6 +704,7 @@ const options = {
   dryRun: args.includes('--dry-run'),
   apply: args.includes('--apply'),
   skipIde: args.includes('--skip-ide'),
+  shared: args.includes('--shared'),
   ide: null,
   path: null,
   file: null,

package/lib/io.js

@@ -139,8 +139,44 @@ function safeCopyDirSync(src, dest) {
   }
 }
 
+/**
+ * Adds Devran AI Kit entries to a project's .gitignore.
+ * Creates .gitignore if it doesn't exist. Idempotent — skips
+ * if entries already present. Uses marker-based detection to
+ * avoid duplicate entries across multiple runs.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @returns {{ added: boolean, reason: string }}
+ */
+function addToGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  const marker = '# Devran AI Kit';
+  const block = [
+    '',
+    '# Devran AI Kit (local dev tooling)',
+    '# Install: npx @devran-ai/kit init',
+    '.agent/',
+  ].join('\n') + '\n';
+
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+    // Primary check: is .agent/ already ignored?
+    if (content.includes('.agent/')) {
+      if (content.includes(marker)) {
+        return { added: false, reason: 'already-present' };
+      }
+      return { added: false, reason: 'already-ignored' };
+    }
+  }
+
+  fs.appendFileSync(gitignorePath, block, 'utf-8');
+  return { added: true, reason: 'added' };
+}
+
 module.exports = {
   writeJsonAtomic,
   readJsonSafe,
   safeCopyDirSync,
+  addToGitignore,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devran-ai/kit",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Trust-grade AI development framework — zero-dependency runtime engine for agent orchestration, workflow governance, and skill management.",
   "main": "bin/kit.js",
   "bin": {