@devran-ai/kit 4.1.0 → 4.2.1

package/.agent/CheatSheet.md

@@ -1,6 +1,6 @@
 # Devran AI Kit — CheatSheet
 
-> **Version**: v4.1.0 | **Quick Reference** for all capabilities
+> **Version**: v4.2.1 | **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.1** — 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.1",
   "lastAuditedAt": null,
   "description": "Devran AI Kit — Trust-Grade AI Development Framework",
   "repository": "https://github.com/devran-ai/kit",

package/README.md

@@ -1,8 +1,8 @@
 # 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.1-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/)
+[![Tests](https://img.shields.io/badge/tests-388%20passing-brightgreen.svg)](tests/)
 [![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
 [![AI Agents](https://img.shields.io/badge/AI%20Agents-23-purple.svg)](.agent/agents/)
 [![Skills](https://img.shields.io/badge/Skills-34-orange.svg)](.agent/skills/)
@@ -26,7 +26,7 @@
 | Self-healing CI | None | None | Auto-diagnoses and patches failures |
 | Cross-IDE support | Single IDE | Single IDE | 5 IDEs from one source of truth |
 | Plugin marketplace | None | None | Trust-verified skill marketplace |
-| Test suite | None | None | 382+ tests with security validation |
+| Test suite | None | None | 388+ tests with security validation |
 | Runtime dependencies | Varies | Varies | **Zero** |
 
 ## Quick Start
@@ -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
@@ -84,7 +95,24 @@ IDLE -> EXPLORE -> PLAN -> IMPLEMENT -> VERIFY -> CHECKPOINT -> REVIEW -> DEPLOY
 
 Each phase requires explicit developer approval before transitioning. The engine enforces governance rules and tracks session state across restarts.
 
-## What's New in v4.1.0
+## What's New
+
+### v4.2.1
+
+| Change | Details |
+|---|---|
+| Untrack hint | Detects tracked `.agent/` and prints `git rm --cached` command |
+| Documentation fixes | Updated release notes, stale test counts corrected |
+
+### v4.2.0
+
+| Change | Details |
+|---|---|
+| Gitignore by default | `kit init` adds `.agent/` to `.gitignore` — personal dev tooling |
+| `--shared` flag | Opt-in to commit `.agent/` for team sharing |
+| 388 tests | 37 test suites across unit, structural, and security |
+
+### v4.1.0
 
 | Change | Details |
 |---|---|
@@ -92,7 +120,6 @@ Each phase requires explicit developer approval before transitioning. The engine
 | Multi-language reviewers | TypeScript, Python, Go dedicated review agents |
 | Continuous learning | Confidence scoring with time-based decay model |
 | MCP server templates | GitHub, Supabase, Vercel, PostgreSQL, Filesystem |
-| Test coverage | 382 tests (up from 348) across 36 test suites |
 
 ## Cross-IDE Support
 
@@ -189,7 +216,7 @@ kit/
 ├── create-kit-app/         # Project scaffolder
 ├── docs/                   # MkDocs documentation site
 ├── examples/               # Starter examples (minimal, full-stack)
-└── tests/                  # 382 tests (unit, structural, security)
+└── tests/                  # 388 tests (unit, structural, security)
 ```
 
 ## Security

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,39 @@ function initCommand(options) {
   }
   currentStep++;
 
+  // Add .agent/ to .gitignore (unless --shared)
+  if (!options.shared) {
+    const { addToGitignore } = require('../lib/io');
+    const { execSync } = require('child_process');
+    logStep(`${currentStep}/${totalSteps}`, 'Configuring .gitignore...');
+    try {
+      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');
+    }
+    // Detect if .agent/ is still git-tracked despite being gitignored
+    try {
+      const tracked = execSync('git ls-files .agent/', { cwd: targetDir, encoding: 'utf-8' }).trim();
+      if (tracked.length > 0) {
+        log('', 'reset');
+        log('   ⚠️  .agent/ is gitignored but still tracked by git.', 'yellow');
+        log('   Run this to untrack (keeps local files):', 'yellow');
+        log(`   ${colors.cyan}git rm -r --cached .agent/${colors.reset}`, 'reset');
+      }
+    } catch (err) {
+      // Not a git repo or git not available — skip hint
+    }
+  } 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 +717,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.1",
   "description": "Trust-grade AI development framework — zero-dependency runtime engine for agent orchestration, workflow governance, and skill management.",
   "main": "bin/kit.js",
   "bin": {