claude-code-superkit 0.0.0-stage → 1.5.3

package/bin/inject-tokens.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// Inject `tokens: N` metadata into YAML frontmatter of all agents, skills, rules.
+// Transparency only — not a budget. Authors should update when editing.
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { measureTokens } from './measure-tokens.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, '..');
+
+const DRY_RUN = process.argv.includes('--dry-run');
+
+// Collect target files
+function walkDir(dir, pattern = /\.md$/) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && pattern.test(entry.name)) {
+        results.push(full);
+      }
+    }
+  }
+  return results;
+}
+
+function collectTargets() {
+  const targets = new Set();
+
+  // Agents
+  for (const p of [
+    'packages/core/agents',
+    'packages/stack-agents',
+    'packages/frontend-3d/agents',
+    'packages/frontend-ui/agents',
+  ]) {
+    walkDir(path.join(ROOT, p)).forEach(f => targets.add(f));
+  }
+
+  // Extras flat files (only .md at top level of packages/extras)
+  const extrasDir = path.join(ROOT, 'packages/extras');
+  if (fs.existsSync(extrasDir)) {
+    for (const entry of fs.readdirSync(extrasDir, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        targets.add(path.join(extrasDir, entry.name));
+      }
+    }
+  }
+
+  // Skills — only SKILL.md files
+  for (const p of [
+    'packages/core/skills',
+    'packages/frontend-3d/skills',
+    'packages/frontend-ui/skills',
+  ]) {
+    walkDir(path.join(ROOT, p), /^SKILL\.md$/).forEach(f => targets.add(f));
+  }
+  const skillsmp = path.join(ROOT, 'packages/extras/skillsmp-search/SKILL.md');
+  if (fs.existsSync(skillsmp)) targets.add(skillsmp);
+
+  // Rules
+  for (const p of [
+    'packages/core/rules',
+    'packages/stack-rules',
+    'packages/frontend-3d/rules',
+    'packages/frontend-ui/rules',
+  ]) {
+    walkDir(path.join(ROOT, p)).forEach(f => targets.add(f));
+  }
+
+  return Array.from(targets).sort();
+}
+
+// Parse/modify frontmatter. Returns { status, oldTokens, newTokens, content }.
+// status: 'updated' | 'inserted' | 'kept' | 'skipped-no-frontmatter' | 'skipped-malformed'
+function processFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+
+  // Detect frontmatter: must start with "---\n" and have a closing "---\n" later
+  if (!raw.startsWith('---\n') && !raw.startsWith('---\r\n')) {
+    return { status: 'skipped-no-frontmatter' };
+  }
+
+  // Find end of frontmatter
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!match) {
+    return { status: 'skipped-malformed' };
+  }
+
+  const frontmatterBlock = match[0];
+  const frontmatterBody = match[1];
+  const body = raw.slice(frontmatterBlock.length);
+  const newTokens = Math.round(body.length / 4);
+
+  // Look for existing tokens field
+  const lines = frontmatterBody.split(/\r?\n/);
+  const tokensIdx = lines.findIndex(l => /^tokens:\s*\d+\s*$/.test(l));
+
+  if (tokensIdx !== -1) {
+    const existing = parseInt(lines[tokensIdx].match(/^tokens:\s*(\d+)/)[1], 10);
+    // Within ±20%? Leave alone.
+    const tolerance = existing * 0.2;
+    if (Math.abs(existing - newTokens) <= tolerance) {
+      return { status: 'kept', oldTokens: existing, newTokens };
+    }
+    // Update in place
+    lines[tokensIdx] = `tokens: ${newTokens}`;
+    const newFrontmatter = `---\n${lines.join('\n')}\n---\n`;
+    return {
+      status: 'updated',
+      oldTokens: existing,
+      newTokens,
+      content: newFrontmatter + body,
+    };
+  }
+
+  // Insert. After `description:` line if exists, else before closing ---
+  const descIdx = lines.findIndex(l => /^description:/.test(l));
+  if (descIdx !== -1) {
+    // Handle possible multi-line description (YAML block) — find next top-level key
+    let insertAt = descIdx + 1;
+    // If the description continues onto next lines (indented), skip those.
+    // Blank lines inside a YAML block scalar are continuations too — skip a
+    // blank line when a later indented line follows (fixes tokens: being
+    // inserted mid-description in multi-paragraph block descriptions).
+    while (insertAt < lines.length) {
+      if (/^\s+/.test(lines[insertAt])) {
+        insertAt++;
+      } else if (
+        lines[insertAt].trim() === '' &&
+        insertAt + 1 < lines.length &&
+        /^\s+/.test(lines[insertAt + 1])
+      ) {
+        insertAt++;
+      } else {
+        break;
+      }
+    }
+    lines.splice(insertAt, 0, `tokens: ${newTokens}`);
+  } else {
+    lines.push(`tokens: ${newTokens}`);
+  }
+
+  const newFrontmatter = `---\n${lines.join('\n')}\n---\n`;
+  return {
+    status: 'inserted',
+    newTokens,
+    content: newFrontmatter + body,
+  };
+}
+
+// Main
+const targets = collectTargets();
+const counts = { updated: 0, inserted: 0, kept: 0, skippedNoFm: 0, skippedMalformed: 0 };
+const tokenValues = [];
+const skipped = [];
+const changes = [];
+
+for (const file of targets) {
+  const result = processFile(file);
+  const rel = path.relative(ROOT, file);
+  switch (result.status) {
+    case 'updated':
+      counts.updated++;
+      tokenValues.push({ file: rel, tokens: result.newTokens });
+      changes.push(`UPDATE ${rel}: ${result.oldTokens} → ${result.newTokens}`);
+      if (!DRY_RUN) fs.writeFileSync(file, result.content);
+      break;
+    case 'inserted':
+      counts.inserted++;
+      tokenValues.push({ file: rel, tokens: result.newTokens });
+      changes.push(`INSERT ${rel}: ${result.newTokens}`);
+      if (!DRY_RUN) fs.writeFileSync(file, result.content);
+      break;
+    case 'kept':
+      counts.kept++;
+      tokenValues.push({ file: rel, tokens: result.oldTokens });
+      break;
+    case 'skipped-no-frontmatter':
+      counts.skippedNoFm++;
+      skipped.push(`${rel} — no frontmatter`);
+      break;
+    case 'skipped-malformed':
+      counts.skippedMalformed++;
+      skipped.push(`${rel} — malformed frontmatter`);
+      break;
+  }
+}
+
+console.log(`\n=== inject-tokens ${DRY_RUN ? '(DRY RUN)' : ''} ===`);
+console.log(`Targets scanned: ${targets.length}`);
+console.log(`  Inserted: ${counts.inserted}`);
+console.log(`  Updated:  ${counts.updated}`);
+console.log(`  Kept:     ${counts.kept}`);
+console.log(`  Skipped (no frontmatter): ${counts.skippedNoFm}`);
+console.log(`  Skipped (malformed):      ${counts.skippedMalformed}`);
+
+if (changes.length && (DRY_RUN || process.argv.includes('--verbose'))) {
+  console.log('\n--- Changes ---');
+  for (const c of changes) console.log(c);
+}
+
+if (skipped.length) {
+  console.log('\n--- Skipped ---');
+  for (const s of skipped) console.log(s);
+}
+
+// Stats on token distribution
+if (tokenValues.length) {
+  const nums = tokenValues.map(t => t.tokens).sort((a, b) => a - b);
+  const min = nums[0];
+  const max = nums[nums.length - 1];
+  const median = nums[Math.floor(nums.length / 2)];
+  console.log(`\n--- Token distribution (all ${tokenValues.length} files) ---`);
+  console.log(`min=${min} median=${median} max=${max}`);
+}

package/bin/measure-tokens.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Approximate token count using ~4 chars/token heuristic.
+// Measures body only, frontmatter excluded.
+import fs from 'fs';
+
+export function measureTokens(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const body = content.replace(/^---[\s\S]*?---\n/, '');
+  return Math.round(body.length / 4);
+}
+
+// CLI mode
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const file = process.argv[2];
+  if (!file) { console.error('usage: measure-tokens.js <file>'); process.exit(1); }
+  console.log(measureTokens(file));
+}

package/bin/superkit-counts-verify.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+# bin/superkit-counts-verify.sh — convenience wrapper
+#
+# Forwards to the canonical hook at packages/core/hooks/superkit-counts-verify.sh.
+# The canonical path is wired into .claude/settings.json as a PreToolUse hook;
+# this wrapper exists so contributors can run the same check manually from
+# the repo root via `bash bin/superkit-counts-verify.sh` without remembering
+# the full hook path.
+#
+# CLI args (e.g. --check-remote, which verifies the GitHub About description
+# over the network) are forwarded to the canonical hook.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+HOOK="$REPO_ROOT/packages/core/hooks/superkit-counts-verify.sh"
+
+if [ ! -f "$HOOK" ]; then
+  printf 'Error: canonical hook missing at %s\n' "$HOOK" >&2
+  exit 1
+fi
+
+# This convenience wrapper is for MANUAL runs from the repo root. It always
+# synthesises a git-commit payload so the canonical hook runs its count/version
+# checks (instead of early-exiting "not a commit"). It deliberately does NOT
+# read stdin: a previous `[ -t 0 ]` check fell through to reading stdin in
+# non-interactive contexts (CI, detached/backgrounded shells) where stdin has
+# no TTY and no EOF, hanging forever — and silently no-op'd (early-exit) when
+# stdin EOF'd empty. To feed a real PreToolUse payload, invoke the canonical
+# hook ($HOOK) directly; it reads stdin as normal.
+printf '{"tool_input":{"command":"git commit -m verify"}}' | exec bash "$HOOK" "$@"

package/lib/codex.js

@@ -0,0 +1,246 @@
+import { lstatSync, readlinkSync, linkSync, symlinkSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync, renameSync, unlinkSync, openSync, closeSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { info, warn, commandExists } from './utils.js';
+
+const MANIFEST = '.codex/.superkit-manifest.json';
+const BACKUPS = '.codex/.superkit-backups';
+const LOCK = '.codex/.superkit-install.lock';
+const HOOK_ASSETS = ['hooks/superkit.mjs', 'superkit-hooks.json'];
+const skillName = /^[a-z0-9][a-z0-9-]*$/;
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+
+function stat(path) {
+  try { return lstatSync(path); } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+// Do not follow even dangling links, nor write through a linked ancestor.
+// The caller owns the project directory; concurrent external edits are unsupported.
+function checkPath(root, relative, directory = false) {
+  const parts = relative.split('/');
+  for (let i = 0; i < parts.length; i++) {
+    const path = join(root, ...parts.slice(0, i + 1));
+    const entry = stat(path);
+    if (!entry) continue;
+    if (entry.isSymbolicLink()) throw new Error(`Refusing symbolic link: ${path}`);
+    const needDirectory = i < parts.length - 1 || directory;
+    if (needDirectory ? !entry.isDirectory() : !entry.isFile()) {
+      throw new Error(`Expected ${needDirectory ? 'directory' : 'regular file'}: ${path}`);
+    }
+  }
+}
+
+function readHashes(path, manifest) {
+  let record;
+  try {
+    record = JSON.parse(readFileSync(path, 'utf8'));
+    if (!record || (manifest && record.schemaVersion !== 1) ||
+        (!manifest && (record.version !== '1.5.2' || !/^[a-f0-9]{40}$/.test(record.sourceCommit))) ||
+        !record.skills || typeof record.skills !== 'object' || Array.isArray(record.skills) ||
+        Object.entries(record.skills).some(([name, hash]) => !skillName.test(name) || typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash)) ||
+        (manifest && record.assets !== undefined && (!record.assets || typeof record.assets !== 'object' || Array.isArray(record.assets) ||
+          Object.entries(record.assets).some(([name, hash]) => !HOOK_ASSETS.includes(name) || typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash))))) {
+      throw new Error('unsupported schema or invalid skill hashes');
+    }
+  } catch (err) {
+    throw new Error(`Invalid Codex ${manifest ? 'manifest' : 'baseline'} at ${path}: ${err.message}`);
+  }
+  return record;
+}
+
+function loadPackage(packagesDir) {
+  const root = join(packagesDir, 'codex');
+  const templates = [
+    ['AGENTS.md', 'AGENTS.md', 'Created AGENTS.md template'],
+    ['config.toml', '.codex/config.toml', 'Copied shipped Codex config template → .codex/config.toml'],
+    ['rules/default.rules', '.codex/rules/default.rules', 'Created .codex/rules/default.rules (approval policy DSL)']
+  ].map(([source, destination, message]) => {
+    checkPath(root, source);
+    return { destination, message, bytes: readFileSync(join(root, source)) };
+  });
+  checkPath(root, 'skills', true);
+  const skills = [];
+  for (const name of readdirSync(join(root, 'skills')).sort()) {
+    if (!skillName.test(name)) throw new Error(`Invalid packaged Codex skill name: ${name}`);
+    const source = `skills/${name}/SKILL.md`;
+    checkPath(root, source);
+    const bytes = readFileSync(join(root, source));
+    skills.push({ name, destination: `.codex/${source}`, bytes, hash: digest(bytes) });
+  }
+  if (!skills.length) throw new Error('Codex package contains no skills');
+  checkPath(root, 'legacy-baseline.json');
+  const baseline = readHashes(join(root, 'legacy-baseline.json'), false).skills;
+  const assets = HOOK_ASSETS.map(name => {
+    const source = name === 'superkit-hooks.json' ? 'hooks.json' : name;
+    checkPath(root, source);
+    const bytes = readFileSync(join(root, source));
+    if (source === 'hooks.json') {
+      const definition = JSON.parse(bytes.toString('utf8'));
+      if (!definition?.hooks || typeof definition.hooks !== 'object' || Array.isArray(definition.hooks) ||
+          Object.values(definition.hooks).some(groups => !Array.isArray(groups) || groups.some(group =>
+            !group || (group.matcher !== undefined && typeof group.matcher !== 'string') ||
+            !Array.isArray(group.hooks) || !group.hooks.length || group.hooks.some(handler =>
+              !handler || handler.type !== 'command' || typeof handler.command !== 'string' || !handler.command.trim() ||
+              (handler.timeout !== undefined && (!Number.isFinite(handler.timeout) || handler.timeout <= 0)))))) {
+        throw new Error('Invalid packaged hooks.json: expected command hook groups');
+      }
+    }
+    return { name, destination: `.codex/${name}`, bytes, hash: digest(bytes) };
+  });
+  return { skills, templates, baseline, assets };
+}
+
+function writeAtomic(root, relative, bytes) {
+  checkPath(root, relative);
+  const path = join(root, relative);
+  const previous = stat(path);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, bytes, { flag: 'wx', mode: previous ? previous.mode & 0o777 : 0o644 });
+    if (previous) {
+      renameSync(temporary, path);
+    } else {
+      // Atomic publication without replacing a destination that appeared meanwhile.
+      linkSync(temporary, path);
+    }
+  } finally {
+    if (stat(temporary)) unlinkSync(temporary);
+  }
+}
+
+// Intentionally independent of Claude's fresh/merge/overwrite selection.
+// Extra legacy arguments are ignored, preserving the former call signature.
+export function installCodex(projectDir, packagesDir) {
+  const { skills, templates, baseline, assets } = loadPackage(packagesDir);
+  const hadCodex = Boolean(stat(join(projectDir, '.codex')));
+  for (const relative of [MANIFEST, LOCK, '.codex/hooks.json', ...skills.map(s => s.destination), ...assets.map(a => a.destination), ...templates.map(t => t.destination)]) {
+    checkPath(projectDir, relative);
+  }
+  checkPath(projectDir, BACKUPS, true);
+  checkPath(projectDir, '.agents/skills', true);
+  const manifestFile = join(projectDir, MANIFEST);
+  const hadManifest = Boolean(stat(manifestFile));
+  // Validate before creating even the lock or target directory.
+  const previousState = hadManifest ? readHashes(manifestFile, true) : { skills: baseline };
+  const previous = previousState.skills;
+  const configPath = join(projectDir, '.codex/config.toml');
+  // Unknown configuration may already contain inline hooks. Never silently add
+  // a second active source beside it; supply a separate merge template instead.
+  const canCreateHookConfig = !stat(configPath) || readFileSync(configPath).equals(templates.find(t => t.destination === '.codex/config.toml').bytes);
+  if (stat(join(projectDir, LOCK))) throw new Error(`Codex install lock exists: ${join(projectDir, LOCK)}. Check for another installer before removing a stale lock.`);
+  mkdirSync(join(projectDir, '.codex'), { recursive: true });
+  const lock = openSync(join(projectDir, LOCK), 'wx');
+  closeSync(lock);
+  try {
+    if (!commandExists('codex')) {
+      warn('Codex CLI not found. Install: npm install -g @openai/codex');
+      warn('Continuing with file setup anyway...');
+    }
+    const managed = { ...(hadManifest ? previous : {}) };
+    const additions = [];
+    const updates = [];
+    let unchanged = 0;
+    let conflicts = 0;
+    let recognizedLegacy = false;
+    for (const skill of skills) {
+      const destination = join(projectDir, skill.destination);
+      if (!stat(destination)) {
+        additions.push(skill);
+        managed[skill.name] = skill.hash;
+        continue;
+      }
+      const oldBytes = readFileSync(destination);
+      const oldHash = digest(oldBytes);
+      if (!hadManifest && oldHash === previous[skill.name]) recognizedLegacy = true;
+      if (oldHash === skill.hash) {
+        unchanged++;
+        managed[skill.name] = skill.hash;
+      } else if (oldHash === previous[skill.name]) {
+        updates.push({ ...skill, oldBytes });
+        managed[skill.name] = skill.hash;
+      } else {
+        conflicts++;
+        warn(`CONFLICT preserved ${skill.destination} — custom or unrecognized content; compare with packages/codex/skills/${skill.name}/SKILL.md`);
+      }
+    }
+    const managedAssets = { ...(previousState.assets || {}) };
+    const assetAdditions = [];
+    const assetUpdates = [];
+    let assetConflicts = 0;
+    for (const asset of assets) {
+      const destination = join(projectDir, asset.destination);
+      if (!stat(destination)) {
+        assetAdditions.push(asset);
+        managedAssets[asset.name] = asset.hash;
+        continue;
+      }
+      const oldBytes = readFileSync(destination);
+      const oldHash = digest(oldBytes);
+      if (oldHash === asset.hash) {
+        managedAssets[asset.name] = asset.hash;
+      } else if (oldHash === previousState.assets?.[asset.name]) {
+        assetUpdates.push({ ...asset, oldBytes });
+        managedAssets[asset.name] = asset.hash;
+      } else {
+        assetConflicts++;
+        warn(`CONFLICT preserved ${asset.destination} — review custom hook assets before trusting or merging hooks`);
+      }
+    }
+    const replacements = [...updates, ...assetUpdates];
+    const mode = !hadCodex ? 'fresh' : hadManifest || recognizedLegacy ? 'upgrade' : 'merge';
+    info(`Codex mode: ${mode} (independent of .claude)`);
+
+    // Finish all backups before the first replacement. Never reuse/delete an old backup.
+    if (replacements.length) {
+      mkdirSync(join(projectDir, BACKUPS), { recursive: true });
+      const backup = mkdtempSync(join(projectDir, BACKUPS, `${new Date().toISOString().replace(/[:.]/g, '-')}-`));
+      for (const skill of replacements) {
+        const relative = skill.destination.slice('.codex/'.length);
+        mkdirSync(dirname(join(backup, relative)), { recursive: true });
+        writeFileSync(join(backup, relative), skill.oldBytes, { flag: 'wx' });
+      }
+      if (hadManifest) writeFileSync(join(backup, '.superkit-manifest.json'), readFileSync(manifestFile), { flag: 'wx' });
+      info(`Codex backup: ${backup}`);
+    }
+    for (const skill of [...additions, ...assetAdditions, ...replacements]) writeAtomic(projectDir, skill.destination, skill.bytes);
+    for (const template of templates) {
+      if (stat(join(projectDir, template.destination))) {
+        warn(`${template.destination} already exists — skipped to preserve consumer configuration/instructions`);
+      } else {
+        writeAtomic(projectDir, template.destination, template.bytes);
+        info(template.message);
+      }
+    }
+    const hookConfig = '.codex/hooks.json';
+    if (!stat(join(projectDir, hookConfig)) && canCreateHookConfig && !assetConflicts) {
+      writeAtomic(projectDir, hookConfig, assets.find(a => a.name === 'superkit-hooks.json').bytes);
+      info('Created .codex/hooks.json — hooks are configured, not trusted');
+    } else {
+      warn('Hook definitions preserved/not auto-merged; compare .codex/superkit-hooks.json with your active hooks.json or inline [hooks] configuration');
+    }
+    info('Review installed hook scripts and use /hooks to review/trust definitions in a trusted project. Installer does not grant hook trust.');
+    mkdirSync(join(projectDir, '.agents/skills'), { recursive: true });
+    for (const skill of skills) {
+      const link = join(projectDir, '.agents/skills', skill.name);
+      const target = `../../.codex/skills/${skill.name}`;
+      const existing = stat(link);
+      if (!existing) {
+        symlinkSync(target, link, 'dir');
+      } else if (!existing.isSymbolicLink() || readlinkSync(link) !== target) {
+        warn(`DISCOVERY CONFLICT preserved .agents/skills/${skill.name} — installed Superkit skill is at ${skill.destination}; choose your active skill manually`);
+      }
+    }
+    const manifestBytes = JSON.stringify({ schemaVersion: 1, skills: managed, assets: managedAssets }, null, 2) + '\n';
+    if (!hadManifest || readFileSync(manifestFile, 'utf8') !== manifestBytes) writeAtomic(projectDir, MANIFEST, manifestBytes);
+    info(`Codex skills: ${additions.length} added, ${updates.length} updated, ${unchanged} unchanged, ${conflicts} conflicts preserved`);
+    info(`Codex hook assets: ${assetAdditions.length} added, ${assetUpdates.length} updated, ${assetConflicts} conflicts preserved`);
+    if (conflicts) warn('Review preserved conflicts manually; new upstream skill content was not applied to those files.');
+    return additions.length + updates.length;
+  } finally {
+    unlinkSync(join(projectDir, LOCK));
+  }
+}

package/lib/docs-scaffold.js

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readdirSync, statSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { info, warn, copyFile, copyDir, commandExists } from './utils.js';
+
+function findInProject(projectDir, name, maxDepth = 2) {
+  function search(dir, depth) {
+    if (depth > maxDepth) return false;
+    try {
+      for (const entry of readdirSync(dir)) {
+        if (entry === 'node_modules' || entry === '.git' || entry === 'vendor') continue;
+        const full = join(dir, entry);
+        if (entry === name) return true;
+        try {
+          if (statSync(full).isDirectory() && depth < maxDepth) {
+            if (search(full, depth + 1)) return true;
+          }
+        } catch { /* skip */ }
+      }
+    } catch { /* skip */ }
+    return false;
+  }
+  return search(projectDir, 0);
+}
+
+export function scaffoldDocs(projectDir, packagesDir, mode) {
+  mkdirSync(join(projectDir, 'docs', 'architecture'), { recursive: true });
+  mkdirSync(join(projectDir, 'docs', 'trees'), { recursive: true });
+
+  const tmplDir = join(packagesDir, 'core', 'docs-templates', 'architecture');
+  let tmplCount = 0;
+
+  if (existsSync(tmplDir)) {
+    tmplCount = copyDir(tmplDir, join(projectDir, 'docs', 'architecture'), mode, '.md');
+    info(`Copied ${tmplCount} architecture doc templates → docs/architecture/`);
+
+    let removed = 0;
+
+    if (!existsSync(join(projectDir, 'go.mod')) && !findInProject(projectDir, 'go.mod')) {
+      const p = join(projectDir, 'docs', 'architecture', 'backend-layers.md');
+      if (existsSync(p)) { rmSync(p); removed++; }
+    }
+
+    if (!findInProject(projectDir, 'package.json')) {
+      const p = join(projectDir, 'docs', 'architecture', 'frontend-state.md');
+      if (existsSync(p)) { rmSync(p); removed++; }
+    }
+
+    if (!findInProject(projectDir, 'migrations', 3) && !findInProject(projectDir, 'schema.prisma')) {
+      const p = join(projectDir, 'docs', 'architecture', 'database-schema.md');
+      if (existsSync(p)) { rmSync(p); removed++; }
+    }
+
+    if (!findInProject(projectDir, 'Dockerfile') && !findInProject(projectDir, 'docker-compose.yml')) {
+      const p = join(projectDir, 'docs', 'architecture', 'deployment.md');
+      if (existsSync(p)) { rmSync(p); removed++; }
+    }
+
+    if (removed > 0) {
+      info(`Removed ${removed} irrelevant templates (auto-detected)`);
+    }
+  } else {
+    info('Created docs/architecture/ and docs/trees/ directories');
+  }
+
+  generateTree(projectDir);
+}
+
+function generateTree(projectDir) {
+  const treePath = join(projectDir, 'docs', 'trees', 'tree-project.md');
+  const date = new Date().toISOString().slice(0, 10);
+  let treeContent;
+
+  if (commandExists('tree')) {
+    try {
+      treeContent = execSync(
+        `tree "${projectDir}" -I 'node_modules|.git|__pycache__|vendor|dist|build|.next|.cache|*.pyc|.DS_Store' --dirsfirst -L 3`,
+        { stdio: 'pipe', maxBuffer: 1024 * 1024 }
+      ).toString();
+    } catch {
+      treeContent = generateFallbackTree(projectDir);
+    }
+  } else {
+    treeContent = generateFallbackTree(projectDir);
+  }
+
+  const content = [
+    '# Project Tree',
+    `> Auto-generated on ${date}. Regenerate with tree-generator agent.`,
+    '',
+    '```',
+    treeContent.trimEnd(),
+    '```',
+    ''
+  ].join('\n');
+
+  writeFileSync(treePath, content);
+  info('Generated project tree → docs/trees/tree-project.md');
+}
+
+function generateFallbackTree(rootDir, maxDepth = 3) {
+  const IGNORE = new Set([
+    'node_modules', '.git', '__pycache__', 'vendor', 'dist',
+    'build', '.next', '.cache', '.DS_Store'
+  ]);
+
+  const lines = [];
+  let count = 0;
+  const MAX_ENTRIES = 100;
+
+  function walk(dir, prefix, depth) {
+    if (depth > maxDepth || count >= MAX_ENTRIES) return;
+    let entries;
+    try {
+      entries = readdirSync(dir).filter(e => !IGNORE.has(e) && !e.endsWith('.pyc')).sort();
+    } catch { return; }
+
+    const dirs = entries.filter(e => {
+      try { return statSync(join(dir, e)).isDirectory(); } catch { return false; }
+    });
+    const files = entries.filter(e => {
+      try { return statSync(join(dir, e)).isFile(); } catch { return false; }
+    });
+    const sorted = [...dirs, ...files];
+
+    for (let i = 0; i < sorted.length && count < MAX_ENTRIES; i++) {
+      const entry = sorted[i];
+      const isLast = i === sorted.length - 1;
+      const connector = isLast ? '└── ' : '├── ';
+      const childPrefix = isLast ? '    ' : '│   ';
+
+      lines.push(`${prefix}${connector}${entry}`);
+      count++;
+
+      const full = join(dir, entry);
+      try {
+        if (statSync(full).isDirectory()) {
+          walk(full, prefix + childPrefix, depth + 1);
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  lines.push('.');
+  walk(rootDir, '', 0);
+  return lines.join('\n');
+}