@dtlabs/ai-toolkit 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,4 +1,46 @@
 ## 0.1.4 (2026-07-21)
+## [0.8.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.7.0...v0.8.0) (2026-08-04)
+
+
+### Features
+
+* **FTR-011:** implement shared infrastructure (INFRA) ([718b0eb](https://github.com/dtlab-tech/ai-toolkit/commit/718b0ebe684814028b0457351a40b171ea80a197))
+* **FTR-011:** implement US-01 — Implement readManifest() Function ([aad7de1](https://github.com/dtlab-tech/ai-toolkit/commit/aad7de19aa6aaf48578c46eebd3bb236ebb4fadb))
+* **FTR-011:** implement US-02 — Implement computeOrphans() Function ([3a70517](https://github.com/dtlab-tech/ai-toolkit/commit/3a705173e649aa7782d036b5790c830c88a1d797))
+* **FTR-011:** implement US-03 — Implement moveToTrash() Function ([a6ac7d2](https://github.com/dtlab-tech/ai-toolkit/commit/a6ac7d2d841905bba24f5349a7d763c9f43527e8))
+* **FTR-011:** implement US-04 — Implement writeManifest() Function ([dc43ea1](https://github.com/dtlab-tech/ai-toolkit/commit/dc43ea1e35c2e4981876ad5f46b3138890851fcd))
+* **FTR-011:** implement US-05 — Integrate Prune Phase into runInstall() and Add UI Display ([bca87ea](https://github.com/dtlab-tech/ai-toolkit/commit/bca87ea8f8843f6a8a07371eaef072b1fc004453))
+* **FTR-011:** implement US-06 — Add CI Safety Net — Agent Name-to-Filename Alignment Check ([06db318](https://github.com/dtlab-tech/ai-toolkit/commit/06db3180b4867b611a2793bf2c74e8510e66827c))
+* **FTR-011:** Installer Manifest and Orphan Pruning ([764eff4](https://github.com/dtlab-tech/ai-toolkit/commit/764eff4dd3b13ee34e7e4be7159c08168e49fe1d))
+* **FTR-011:** update effort and token estimates, add implementation summary, and log completion details ([ce5660d](https://github.com/dtlab-tech/ai-toolkit/commit/ce5660dec691b75bb501bcadb149c2f4eaabdb5a))
+* **FTR-012:** implement shared infrastructure (INFRA) ([da14ae1](https://github.com/dtlab-tech/ai-toolkit/commit/da14ae15d19301c47231e73872ecba75f180e739))
+* **FTR-012:** implement US-01 — Fresh Installation with Allowlist Opt-In ([803018a](https://github.com/dtlab-tech/ai-toolkit/commit/803018aafe77abb06390849540f7fb214fccbc40))
+* **FTR-012:** implement US-02 — Merge Allowlist into Existing Settings ([9855abc](https://github.com/dtlab-tech/ai-toolkit/commit/9855abc940443d4e75b7a1b3340715d8e1403fcf))
+* **FTR-012:** implement US-03 — Ask-Beats-Allow Conflict Resolution ([9c51984](https://github.com/dtlab-tech/ai-toolkit/commit/9c5198490824647bac7b1850b09e624d9f00e883))
+* **FTR-012:** implement US-04 — Reinstall with Idempotent Merge ([8e9a49f](https://github.com/dtlab-tech/ai-toolkit/commit/8e9a49f69d7bb761a698b2ac7f7a405d5d2d833e))
+* **FTR-012:** implement US-05 — .gitignore Creation and Idempotent Update ([20e19de](https://github.com/dtlab-tech/ai-toolkit/commit/20e19de3c38cbbfcd5dd27c8b8b5ab629036b101))
+* **FTR-012:** Installer Bash Allowlist ([2deb73e](https://github.com/dtlab-tech/ai-toolkit/commit/2deb73ef4ad4189c6eea1ae46ec0f0dc6ece469e))
+* **FTR-012:** mark feature as completed in registry ([ab90d58](https://github.com/dtlab-tech/ai-toolkit/commit/ab90d5878a4091ccaef38863c14634ebd2082623))
+* **FTR-013:** add additional agent entries for US-03 and US-04 in ledger ([6f756ed](https://github.com/dtlab-tech/ai-toolkit/commit/6f756edfaa0d75b48809aa3964261efa65fd69f9))
+* **FTR-013:** add registry entry and update ledger actuals ([23f5138](https://github.com/dtlab-tech/ai-toolkit/commit/23f513801486c36e95782ea513e15fcfcb755d06))
+* **FTR-013:** implement shared infrastructure (INFRA) ([99d564f](https://github.com/dtlab-tech/ai-toolkit/commit/99d564f8ca543b7cd95c5cf1a5687961ef402921))
+* **FTR-013:** implement US-01 — Initialize and Track Ledger in define-feature Agent ([ce0b010](https://github.com/dtlab-tech/ai-toolkit/commit/ce0b010afd40e94f9e9e2618eca1fbcc60ede7ae))
+* **FTR-013:** implement US-01 — Initialize and Track Ledger in define-feature Agent ([ca84538](https://github.com/dtlab-tech/ai-toolkit/commit/ca84538d6980828313d331e4a07e10bde5cb34c7))
+* **FTR-013:** implement US-02 — Track Phase 1 Agent Invocations ([a4e3b10](https://github.com/dtlab-tech/ai-toolkit/commit/a4e3b1001bb0b6201c873c4608c23c94c37ca5e0))
+* **FTR-013:** implement US-02 — Track Phase 1 Agent Invocations ([85d86e4](https://github.com/dtlab-tech/ai-toolkit/commit/85d86e406d9ace96b22214de5aef14a6b0cde0b2))
+* **FTR-013:** implement US-03 — Track Phase 2 Agent Invocations ([819f3c3](https://github.com/dtlab-tech/ai-toolkit/commit/819f3c33a954ce89bb221461ee21092b9429c085))
+* **FTR-013:** implement US-03 — Track Phase 2 Agent Invocations ([7d6f9bb](https://github.com/dtlab-tech/ai-toolkit/commit/7d6f9bba8a794e83a12b31a306e27a5d8505c3f7))
+* **FTR-013:** Ledger Pipeline Activity Tracker ([f1bf49a](https://github.com/dtlab-tech/ai-toolkit/commit/f1bf49a4c7496fba8f0c04c5770fe2ad08a6b4ac))
+* **pm:** add EUR cost columns to Token-Estimate ([b0faf0d](https://github.com/dtlab-tech/ai-toolkit/commit/b0faf0dc15c40358bf64b55a0a34987be8db19a2))
+
+
+### Bug Fixes
+
+* **FTR-011:** remediate review issues ([c34d824](https://github.com/dtlab-tech/ai-toolkit/commit/c34d8246fff5548401cb50cc300043679ede4bba))
+* **FTR-012:** remediate review issues ([f9ea280](https://github.com/dtlab-tech/ai-toolkit/commit/f9ea280c394a6436fa6a0840f0110b1b620b6025))
+* **pm:** commit actuals after write-actuals; restore zero-delta ledger entries on resume ([83bbaec](https://github.com/dtlab-tech/ai-toolkit/commit/83bbaecdbbbbf9aa436af8d56a6e823500868b1b))
+* **pm:** correct write-actuals token estimate output ([d45653a](https://github.com/dtlab-tech/ai-toolkit/commit/d45653a2c9f999ec8478836e01128428295fa95a))
+
 ## [0.7.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.6.0...v0.7.0) (2026-07-29)
 
 

package/bin/cli.js

@@ -67,6 +67,92 @@ function askConfirm(question) {
   });
 }
 
+// ── allowlist ─────────────────────────────────────────────────────────────────
+
+// INFRA-T01: Canonical Bash permission lists (FTR-012, AC-11, AC-12).
+// These are fixed baselines — one combined list covering base read-only,
+// .NET, and npm commands. Unused entries in a project are harmless.
+const CANONICAL_ALLOW = [
+  'ls', 'dir', 'cat', 'head', 'tail', 'find', 'grep', 'rg', 'wc', 'echo',
+  'pwd', 'which', 'date',
+  'git status', 'git diff', 'git log', 'git show', 'git branch', 'git rev-parse',
+  'git add', 'git commit',
+  'dotnet build', 'dotnet test', 'dotnet restore',
+  'npm test', 'npm run build',
+];
+
+// Dangerous outward-facing commands that must always surface a human prompt.
+// git checkout stays on ask: it runs only in the implement-feature main loop
+// (Step 5), never inside pm-phase3 worker agents. If pm-phase3 ever gains
+// branch-management steps, this decision must be revisited.
+const CANONICAL_ASK = [
+  'git push', 'gh pr create', 'rm', 'del',
+  'git checkout', 'git reset', 'git clean',
+];
+
+// INFRA-T01: Format a raw command string into a Claude Code permission token.
+// Every command — including no-argument ones like 'pwd' — is formatted as
+// 'Bash(<cmd>:*)' for consistency across all entries.
+function commandToPermission(cmd) {
+  return `Bash(${cmd}:*)`;
+}
+
+// INFRA-T02: Ensure an object parsed from settings.local.json has the expected
+// shape. Mutates and returns the object so callers can chain immediately.
+function normalizeSettings(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) obj = {};
+  if (!obj.permissions || typeof obj.permissions !== 'object') obj.permissions = {};
+  if (!obj.permissions.Bash || typeof obj.permissions.Bash !== 'object') obj.permissions.Bash = {};
+  if (!Array.isArray(obj.permissions.Bash.allow)) obj.permissions.Bash.allow = [];
+  if (!Array.isArray(obj.permissions.Bash.ask)) obj.permissions.Bash.ask = [];
+  return obj;
+}
+
+// INFRA-T03: Return the dedup union of two arrays (preserves insertion order,
+// all elements of a appear before novel elements of b).
+function mergeArrays(a, b) {
+  return [...new Set([...a, ...b])];
+}
+
+// INFRA-T03: Remove from allow every entry that also appears in ask.
+// This enforces the ask-beats-allow invariant: a command that could be
+// dangerous is never silently auto-approved just because it was also listed
+// in an allow array.
+function applyAskBeatsAllow(allow, ask) {
+  const askSet = new Set(ask);
+  return allow.filter(cmd => !askSet.has(cmd));
+}
+
+// INFRA-T04: Read {destDir}/.claude/settings.local.json.
+// Returns a descriptor so callers can distinguish missing vs. malformed.
+//   { exists: false, data: null,  malformed: false }  — file absent
+//   { exists: true,  data: <obj>, malformed: false }  — parsed OK
+//   { exists: true,  data: null,  malformed: true  }  — invalid JSON
+function readSettings(destDir) {
+  const settingsPath = path.join(destDir, '.claude', 'settings.local.json');
+  if (!fs.existsSync(settingsPath)) return { exists: false, data: null, malformed: false };
+  let raw;
+  try { raw = fs.readFileSync(settingsPath, 'utf8'); } catch (err) {
+    console.error(`Warning: could not read settings.local.json — ${err.message}`);
+    return { exists: true, data: null, malformed: true };
+  }
+  try {
+    const data = JSON.parse(raw);
+    return { exists: true, data, malformed: false };
+  } catch {
+    return { exists: true, data: null, malformed: true };
+  }
+}
+
+// INFRA-T04: Write {destDir}/.claude/settings.local.json, creating the
+// .claude/ directory if it does not exist. Throws on I/O failure so callers
+// can catch and report gracefully.
+function writeSettings(destDir, data) {
+  const settingsPath = path.join(destDir, '.claude', 'settings.local.json');
+  ensureDir(settingsPath);
+  fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2), 'utf8');
+}
+
 // ── file enumeration ─────────────────────────────────────────────────────────
 
 function expandMappings(mappings) {
@@ -155,9 +241,71 @@ async function checkVersion(destRoot, force) {
   return true;
 }
 
+// ── manifest ──────────────────────────────────────────────────────────────────
+
+const MANIFEST_FILE = '.ai-toolkit-manifest.json';
+
+function readManifest(destRoot) {
+  const manifestPath = path.join(destRoot, '.claude', MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return { files: [] };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    if (!parsed || !Array.isArray(parsed.files)) return { files: [] };
+    parsed.files = parsed.files.map(f => f.replace(/\\/g, '/'));
+    return parsed;
+  } catch {
+    console.log(dim('Previous manifest is corrupt; treating as empty'));
+    return { files: [] };
+  }
+}
+
+function computeOrphans(oldFiles, newFiles) {
+  const newSet = new Set(newFiles.map(f => f.replace(/\\/g, '/')));
+  return oldFiles
+    .map(f => f.replace(/\\/g, '/'))
+    .filter(f => !newSet.has(f));
+}
+
+function moveToTrash(destRoot, relativePath) {
+  const source = path.join(destRoot, relativePath);
+  if (!fs.existsSync(source)) return;
+  const trashPath = path.join(destRoot, '.claude', '.ai-toolkit-trash', relativePath);
+  ensureDir(trashPath);
+  try {
+    fs.renameSync(source, trashPath);
+  } catch (err) {
+    if (err.code === 'EXDEV') {
+      fs.copyFileSync(source, trashPath);
+      fs.unlinkSync(source);
+    } else {
+      throw err;
+    }
+  }
+}
+
+function writeManifest(destRoot, fileList) {
+  const manifestPath = path.join(destRoot, '.claude', MANIFEST_FILE);
+  const trashDir = path.join(destRoot, '.claude', '.ai-toolkit-trash');
+  const filtered = fileList.filter(rel => {
+    const abs = path.join(destRoot, rel);
+    return !abs.startsWith(trashDir + path.sep) && abs !== trashDir;
+  });
+  const manifest = {
+    version: TOOLKIT_VERSION,
+    installedAt: new Date().toISOString(),
+    files: filtered.map(f => f.replace(/\\/g, '/')),
+  };
+  try {
+    ensureDir(manifestPath);
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+  } catch (err) {
+    console.log(dim(`Warning: could not write manifest — ${err.message}`));
+  }
+}
+
 // ── install ───────────────────────────────────────────────────────────────────
 
-async function runInstall(label, mappings, force) {
+async function runInstall(label, mappings, force, destRoot) {
   const files    = expandMappings(mappings);
   const entries  = categorize(files);
 
@@ -165,6 +313,58 @@ async function runInstall(label, mappings, force) {
   const modified = entries.filter(e => e.status === 'modified');
   const same     = entries.filter(e => e.status === 'same');
 
+  // ── prune phase (before file copy) ───────────────────────────────────────────
+  const oldManifest = readManifest(destRoot);
+  const newFileSet  = files.map(f => path.relative(destRoot, f.dest).replace(/\\/g, '/'));
+  const orphans     = computeOrphans(oldManifest.files, newFileSet);
+
+  const existingOrphans = orphans.filter(o => fs.existsSync(path.join(destRoot, o)));
+
+  if (existingOrphans.length > 0) {
+    console.log();
+    console.log(`${bold('📦 Orphan cleanup')}  ${clr('gray', '→')}  ${clr('red', `${existingOrphans.length} stale file(s) found`)}`);
+    console.log(divider());
+    for (const orphan of existingOrphans) {
+      console.log(`  ${clr('red', '∅')} ${clr('red', 'REMOVED ')}  ${orphan}`);
+    }
+    console.log(divider());
+  }
+
+  let removedCount = 0;
+  let keptCount    = 0;
+
+  if (force) {
+    for (const orphan of existingOrphans) {
+      moveToTrash(destRoot, orphan);
+      removedCount++;
+      console.log(`     ${clr('red', '∅')} ${dim(orphan)}`);
+    }
+  } else {
+    for (const orphan of existingOrphans) {
+      const fullPath = path.join(destRoot, orphan);
+      if (!fs.existsSync(fullPath)) continue;
+      const ok = await askConfirm(`  Move to trash  ${clr('red', orphan)}?`);
+      if (ok) {
+        moveToTrash(destRoot, orphan);
+        console.log(`     ${clr('green', '✔')} Moved to trash\n`);
+        removedCount++;
+      } else {
+        console.log(`     ${clr('gray', '✖')} Kept as-is\n`);
+        keptCount++;
+      }
+    }
+  }
+
+  if (existingOrphans.length > 0) {
+    console.log(divider());
+    console.log(
+      `  ${clr('red', `∅ Moved: ${removedCount}`)}` +
+      `  ${clr('gray', `↪ .claude/.ai-toolkit-trash/`)}` +
+      `  ${clr('gray', `✖ Kept: ${keptCount}`)}\n`
+    );
+  }
+
+  // ── install plan display ──────────────────────────────────────────────────────
   console.log();
   console.log(`${bold('📦 Install plan')}  ${clr('gray', '→')}  ${clr('cyan', label)}`);
   console.log(divider());
@@ -186,6 +386,7 @@ async function runInstall(label, mappings, force) {
 
   if (modified.length === 0) {
     console.log(`  ${clr('green', '✔')}  All new files copied. No conflicts.\n`);
+    writeManifest(destRoot, newFileSet);
     return;
   }
 
@@ -196,6 +397,7 @@ async function runInstall(label, mappings, force) {
       fs.copyFileSync(e.src, e.dest);
       console.log(`     ${clr('yellow', '↺')} ${dim(path.relative(process.cwd(), e.dest))}`);
     }
+    writeManifest(destRoot, newFileSet);
     return;
   }
 
@@ -223,6 +425,8 @@ async function runInstall(label, mappings, force) {
     `  ${clr('green', `✔ Overwritten: ${overwritten}`)}` +
     `  ${clr('gray',  `✖ Kept as-is: ${skipped}`)}\n`
   );
+
+  writeManifest(destRoot, newFileSet);
 }
 
 // ── subagent spawn-depth check (verify & advise only — never write) ────────────
@@ -271,6 +475,175 @@ function checkSpawnDepth(destRoot) {
   console.log(`     ${dim('Then restart Claude Code so the variable is loaded.')}\n`);
 }
 
+// ── mergeAllowlist ────────────────────────────────────────────────────────────
+
+// US-01-T01 / US-02-T01 / US-02-T02 / US-03-T01:
+// Core pure function — creates or merges the Bash permission allowlist in
+// {destDir}/.claude/settings.local.json using the canonical lists above.
+//
+// Return values:
+//   { status: 'written' }                     — fresh file created
+//   { status: 'merged', preserved: N }        — merged with N pre-existing rules
+//   { status: 'reset',  reason: 'malformed' } — invalid JSON was replaced
+//   { status: 'error',  message: '...' }      — I/O failure
+function mergeAllowlist(destDir) {
+  if (!destDir || typeof destDir !== 'string') {
+    return { status: 'error', message: 'destDir must be a non-empty string' };
+  }
+  if (!fs.existsSync(destDir) || !fs.statSync(destDir).isDirectory()) {
+    return { status: 'error', message: `destination does not exist or is not a directory: ${destDir}` };
+  }
+
+  const canonicalAllow = CANONICAL_ALLOW.map(commandToPermission);
+  const canonicalAsk   = CANONICAL_ASK.map(commandToPermission);
+
+  const { exists, data, malformed } = readSettings(destDir);
+
+  // Malformed JSON recovery (AC-05)
+  if (malformed) {
+    console.log('Warning: settings.local.json is not valid JSON; resetting to default');
+    const fresh = normalizeSettings({});
+    fresh.permissions.Bash.allow = canonicalAllow;
+    fresh.permissions.Bash.ask   = canonicalAsk;
+    try {
+      writeSettings(destDir, fresh);
+    } catch (err) {
+      return { status: 'error', message: err.message };
+    }
+    return { status: 'reset', reason: 'malformed' };
+  }
+
+  // Fresh install: no existing file (AC-01)
+  if (!exists) {
+    const fresh = normalizeSettings({});
+    fresh.permissions.Bash.allow = canonicalAllow;
+    fresh.permissions.Bash.ask   = canonicalAsk;
+    try {
+      writeSettings(destDir, fresh);
+    } catch (err) {
+      return { status: 'error', message: err.message };
+    }
+    return { status: 'written' };
+  }
+
+  // Merge path: existing file, valid JSON (AC-02, AC-03, AC-04)
+  const existing = normalizeSettings(data);
+  const existingAllow = existing.permissions.Bash.allow;
+  const existingAsk   = existing.permissions.Bash.ask;
+
+  const countBefore = existingAllow.length + existingAsk.length;
+
+  let mergedAllow = mergeArrays(existingAllow, canonicalAllow);
+  const mergedAsk = mergeArrays(existingAsk,   canonicalAsk);
+
+  // ask-beats-allow: strip from allow any cmd that is now in ask
+  mergedAllow = applyAskBeatsAllow(mergedAllow, mergedAsk);
+
+  existing.permissions.Bash.allow = mergedAllow;
+  existing.permissions.Bash.ask   = mergedAsk;
+
+  try {
+    writeSettings(destDir, existing);
+  } catch (err) {
+    return { status: 'error', message: err.message };
+  }
+
+  const preserved = countBefore;
+  return { status: 'merged', preserved };
+}
+
+// INFRA-T01 (FTR-013):
+// Append a new entry to {featureDir}/{prefix}-token-ledger.json atomically.
+// If the file does not exist it is created. If JSON is malformed the file is
+// overwritten with a single-element array containing the new entry.
+//
+// Algorithm:
+//   1. Read and parse the existing ledger (or start with [])
+//   2. Push the new entry
+//   3. Write the full array back in one synchronous write (atomic)
+function appendLedgerEntry(featureDir, prefix, entry) {
+  const filePath = path.join(featureDir, `${prefix}-token-ledger.json`);
+  let ledger = [];
+  if (fs.existsSync(filePath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      ledger = Array.isArray(parsed) ? parsed : [];
+    } catch (_) {
+      console.log(`Warning: could not parse token ledger at ${filePath} — starting fresh`);
+      ledger = [];
+    }
+  }
+  ledger.push(entry);
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2), 'utf8');
+}
+
+// INFRA-T02 (FTR-013):
+// Find and update an existing entry in {featureDir}/{prefix}-token-ledger.json
+// by agent key, atomically. Searches from the end of the array so that the most
+// recent entry for a given key is updated (handles any accidental duplicates).
+// If the file does not exist or the key is not found the call is a silent no-op.
+//
+// Algorithm:
+//   1. Read and parse the existing ledger (silent return on missing/malformed)
+//   2. Find the last entry where entry.agent === agentKey
+//   3. Object.assign the updates onto that entry
+//   4. Write the full array back in one synchronous write (atomic)
+function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
+  const filePath = path.join(featureDir, `${prefix}-token-ledger.json`);
+  if (!fs.existsSync(filePath)) return;
+  let ledger;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    ledger = Array.isArray(parsed) ? parsed : [];
+  } catch (_) {
+    console.log(`Warning: could not parse token ledger at ${filePath} — skipping update for "${agentKey}"`);
+    return;
+  }
+  let idx = -1;
+  for (let i = ledger.length - 1; i >= 0; i--) {
+    if (ledger[i] && ledger[i].agent === agentKey) { idx = i; break; }
+  }
+  if (idx === -1) {
+    console.log(`Warning: ledger entry not found for agent key "${agentKey}"`);
+    return;
+  }
+  Object.assign(ledger[idx], updates);
+  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2), 'utf8');
+}
+
+// US-05-T01:
+// Idempotently append `.claude/settings.local.json` to {destDir}/.gitignore.
+// Creates .gitignore if it does not exist (AC-06, AC-07).
+//
+// Return values:
+//   { status: 'appended' }     — line was added
+//   { status: 'already' }      — line was already present
+//   { status: 'created' }      — .gitignore did not exist; created with line
+//   { status: 'error', message } — I/O failure
+function updateGitignore(destDir) {
+  const GITIGNORE_ENTRY = '.claude/settings.local.json';
+  const gitignorePath   = path.join(destDir, '.gitignore');
+
+  try {
+    if (!fs.existsSync(gitignorePath)) {
+      fs.writeFileSync(gitignorePath, `${GITIGNORE_ENTRY}\n`, 'utf8');
+      return { status: 'created' };
+    }
+
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    const lines   = content.split('\n').map(l => l.trim());
+    if (lines.includes(GITIGNORE_ENTRY)) return { status: 'already' };
+
+    const trailing = content.endsWith('\n') ? '' : '\n';
+    fs.writeFileSync(gitignorePath, `${content}${trailing}${GITIGNORE_ENTRY}\n`, 'utf8');
+    return { status: 'appended' };
+  } catch (err) {
+    return { status: 'error', message: err.message };
+  }
+}
+
 // ── entry points ──────────────────────────────────────────────────────────────
 
 async function installLocal(targetDir, force) {
@@ -283,7 +656,7 @@ async function installLocal(targetDir, force) {
     { src: path.join(packageRoot, 'docs'),      dest: path.join(targetDir, 'docs') },
     { src: path.join(packageRoot, 'CLAUDE.md'), dest: path.join(targetDir, 'CLAUDE.md') },
   ];
-  await runInstall(`local project`, mappings, force);
+  await runInstall(`local project`, mappings, force, targetDir);
   writeInstalledVersion(targetDir);
   console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
   checkSpawnDepth(targetDir);
@@ -309,7 +682,7 @@ async function installGlobal(force) {
       { src: path.join(packageRoot, 'docs'),                 dest: path.join(target, 'docs') },
       { src: path.join(packageRoot, 'CLAUDE.global.md'),    dest: path.join(target, 'CLAUDE.md') },
     ];
-    await runInstall('global Claude folder', mappings, force);
+    await runInstall('global Claude folder', mappings, force, target);
     writeInstalledVersion(target);
     console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
     checkSpawnDepth(homedir);
@@ -349,6 +722,42 @@ async function main() {
     await installGlobal(force);
   } else if (argv[0] === 'help' || argv[0] === '--help') {
     help();
+  } else if (argv[0] === 'merge-allowlist') {
+    const destDir = argv[1];
+    if (!destDir) {
+      console.error('Error: merge-allowlist requires a destination directory');
+      process.exit(1);
+    }
+    try {
+      const result = mergeAllowlist(destDir);
+      if (result.status === 'error') {
+        console.error(`Error: ${result.message}`);
+        process.exit(1);
+      }
+      console.log(`Allowlist: ${result.status}${result.preserved !== undefined ? ` (${result.preserved} rules preserved)` : ''}`);
+      process.exit(0);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  } else if (argv[0] === 'update-gitignore') {
+    const destDir = argv[1];
+    if (!destDir) {
+      console.error('Error: update-gitignore requires a destination directory');
+      process.exit(1);
+    }
+    try {
+      const result = updateGitignore(destDir);
+      if (result.status === 'error') {
+        console.error(`Error: ${result.message}`);
+        process.exit(1);
+      }
+      console.log(`Gitignore: ${result.status}`);
+      process.exit(0);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
   } else if (fs.existsSync(argv[0]) && fs.statSync(argv[0]).isDirectory()) {
     await installLocal(argv[0], force);
   } else {
@@ -371,5 +780,21 @@ if (require.main === module) {
     categorize,
     readInstalledVersion,
     NEVER_COPY,
+    readManifest,
+    computeOrphans,
+    moveToTrash,
+    writeManifest,
+    CANONICAL_ALLOW,
+    CANONICAL_ASK,
+    commandToPermission,
+    normalizeSettings,
+    mergeArrays,
+    applyAskBeatsAllow,
+    readSettings,
+    writeSettings,
+    mergeAllowlist,
+    updateGitignore,
+    appendLedgerEntry,
+    updateLedgerEntry,
   };
 }

package/docs/token-pricing.json

@@ -0,0 +1,21 @@
+{
+  "_comment": "Anthropic API pricing (USD per 1M tokens). Update when prices change. EUR conversion uses the rate below.",
+  "_source": "https://www.anthropic.com/pricing — last updated 2026-07-31",
+  "_split": "No per-agent input/output breakdown available in the ledger. Assume 80% input / 20% output as a reasonable approximation.",
+  "usd_to_eur": 0.92,
+  "usd_to_eur_date": "2026-07-31",
+  "models": {
+    "haiku": {
+      "input_per_1m_usd": 0.80,
+      "output_per_1m_usd": 4.00
+    },
+    "sonnet": {
+      "input_per_1m_usd": 3.00,
+      "output_per_1m_usd": 15.00
+    },
+    "opus": {
+      "input_per_1m_usd": 15.00,
+      "output_per_1m_usd": 75.00
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",