overarch-darwin-arm64 0.8.0

package/dist/src/cli/commands/companion.js

@@ -0,0 +1,143 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as ui from '../ui.js';
+import { petdexAdapter } from '../../companion/petdex_adapter.js';
+import { petdexBridge } from '../../companion/petdex_bridge.js';
+const execAsync = promisify(exec);
+export async function handleCompanionCommand(subcommand, arg1, _arg2) {
+    const sub = (subcommand || 'status').toLowerCase();
+    switch (sub) {
+        case 'start':
+        case 'launch': {
+            ui.info('Launching Overarch Desktop Companion...');
+            const res = await petdexBridge.launchCompanion(process.cwd());
+            if (res.success) {
+                ui.success(res.message);
+            }
+            else {
+                ui.warn(res.message);
+                console.log(ui.dim('Ensure dist-desktop/OverarchCompanion.exe is built: npm run build:desktop'));
+            }
+            break;
+        }
+        case 'stop':
+        case 'kill': {
+            try {
+                await execAsync('powershell -Command "Stop-Process -Name \'OverarchCompanion\' -Force -ErrorAction SilentlyContinue"');
+                ui.success('Stopped Overarch Desktop Companion.');
+            }
+            catch (err) {
+                ui.info('No active companion process detected.');
+            }
+            break;
+        }
+        case 'status': {
+            let isProcRunning = false;
+            try {
+                const { stdout } = await execAsync('powershell -Command "Get-Process -Name \'OverarchCompanion\' -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Id"');
+                isProcRunning = Boolean(stdout && stdout.trim());
+            }
+            catch { }
+            const bridgeStatus = petdexBridge.getStatus();
+            const activePet = petdexBridge.getActivePet();
+            const petInfo = await petdexAdapter.getPet(activePet);
+            ui.statusCard('Overarch Desktop Companion Status', {
+                'Desktop Window': isProcRunning ? ui.green('Running (Floating Overlay)') : ui.dim('Not running (start with `overarch companion start`)'),
+                'Active Pet': petInfo ? `${petInfo.displayName} (${petInfo.id})` : activePet,
+                'Format / Version': petInfo ? `${petInfo.spritesheetFormat.toUpperCase()} (v${petInfo.spriteVersionNumber}, ${petInfo.columns}x${petInfo.rows} grid)` : 'Default',
+                'Agent State': bridgeStatus.state.toUpperCase(),
+                'Bridge Event Port': bridgeStatus.port,
+                'Connected Clients': bridgeStatus.connectedClients,
+                'Controls': 'Right-click pet for menu, left-click drag to reposition'
+            });
+            break;
+        }
+        case 'pets':
+        case 'list': {
+            ui.info('Scanning Petdex library...');
+            const pets = await petdexAdapter.listPets();
+            const activePet = petdexBridge.getActivePet();
+            ui.heading(`Available Petdex Pets (${pets.length})`);
+            console.log();
+            if (pets.length === 0) {
+                console.log(ui.dim('  No installed Petdex pets found in ~/.petdex/pets/ or ~/.codex/pets/'));
+                console.log(`  ${ui.dim('Install one with:')} ${ui.accent('overarch companion install <slug>')}`);
+                console.log(`  ${ui.dim('Example:')}      ${ui.accent('overarch companion install savage-codex-hacker')}`);
+                console.log(`  ${ui.dim('Gallery:')}      https://petdex.dev`);
+                return;
+            }
+            pets.forEach((p, idx) => {
+                const isAct = p.id === activePet ? ui.accent(' (active)') : '';
+                console.log(`  ${idx + 1}. ${ui.bold(p.displayName)} ${ui.dim(`[${p.id}]`)}${isAct}`);
+                if (p.description) {
+                    console.log(`     ${ui.dim(p.description)}`);
+                }
+            });
+            console.log(`\n${ui.dim('Switch active pet:')} ${ui.accent('overarch companion select <slug>')}`);
+            console.log(`${ui.dim('Install more pets:')} ${ui.accent('overarch companion install <slug>')}`);
+            break;
+        }
+        case 'select':
+        case 'set': {
+            if (!arg1) {
+                ui.warn('Usage: overarch companion select <slug>');
+                return;
+            }
+            const targetSlug = arg1.trim();
+            const pet = await petdexAdapter.getPet(targetSlug);
+            if (!pet) {
+                ui.warn(`Pet '${targetSlug}' is not installed locally.`);
+                console.log(ui.dim(`Run \`overarch companion install ${targetSlug}\` to install it from Petdex.`));
+                return;
+            }
+            petdexBridge.setActivePet(pet.id);
+            ui.success(`Selected Petdex companion: ${ui.bold(pet.displayName)} (${pet.id})`);
+            break;
+        }
+        case 'install':
+        case 'add': {
+            if (!arg1) {
+                ui.warn('Usage: overarch companion install <slug>');
+                console.log(ui.dim('Example: overarch companion install savage-codex-hacker'));
+                console.log(ui.dim('Browse 200+ pets at: https://petdex.dev'));
+                return;
+            }
+            const slug = arg1.trim();
+            ui.info(`Installing '${slug}' from Petdex library...`);
+            const spin = ui.spinner(`Fetching ${slug} from Petdex...`);
+            const result = await petdexAdapter.installPet(slug);
+            spin.stop();
+            if (result.success) {
+                ui.success(result.message);
+                if (result.pet) {
+                    petdexBridge.setActivePet(result.pet.id);
+                    console.log(ui.dim(`Automatically set ${result.pet.displayName} as active companion.`));
+                }
+            }
+            else {
+                ui.fail(result.message);
+            }
+            break;
+        }
+        case 'help':
+        default: {
+            ui.heading('Overarch Floating Desktop Companion');
+            console.log(`
+${ui.bold('Commands')}
+  overarch companion start          Launch floating desktop companion
+  overarch companion stop           Close companion window
+  overarch companion status         Display companion connection & active pet
+  overarch companion pets           List all installed Petdex companions
+  overarch companion select <slug>  Switch active desktop companion
+  overarch companion install <slug> Install any pet from https://petdex.dev
+
+${ui.bold('Desktop Interaction')}
+  • Left-click & drag:   Move pet anywhere on desktop (position is saved)
+  • Double-click:        Wave / greeting reaction
+  • Right-click:         Context menu (change pet, terminal, status, reset)
+  • Non-activating:      Never steals keyboard focus from editor or terminal
+`);
+            break;
+        }
+    }
+}

package/dist/src/cli/commands/config.d.ts

@@ -0,0 +1 @@
+export declare function handleConfigCommand(subcommand?: string, key?: string, value?: string): Promise<void>;

package/dist/src/cli/commands/config.js

@@ -0,0 +1,135 @@
+import * as ui from '../ui.js';
+import { loadConfig, saveGlobalConfig } from '../../config/index.js';
+import { resolveModel } from '../../providers/factory.js';
+export async function handleConfigCommand(subcommand, key, value) {
+    const config = await loadConfig();
+    // 1. Direct Target Shortcuts
+    if (subcommand === 'provider') {
+        if (!key) {
+            console.log(`\nActive Provider: ${ui.bold(config.activeProvider || 'anthropic')}`);
+            console.log(`Provider Mode:   ${config.mode === 'offline' ? ui.yellow('Offline') : ui.green('Online')}`);
+            console.log(ui.dim('To change provider: overarch config set provider <anthropic|openai|gemini|openrouter>'));
+            return;
+        }
+        await saveGlobalConfig({ activeProvider: key.toLowerCase() });
+        ui.success(`Active provider set to: ${key.toLowerCase()}`);
+        return;
+    }
+    if (subcommand === 'model') {
+        if (!key) {
+            const resolved = resolveModel(config.defaultModel);
+            console.log(`\nActive Model: ${ui.bold(config.defaultModel)}`);
+            if (resolved) {
+                console.log(`Display Name: ${resolved.displayName} (${resolved.provider})`);
+            }
+            console.log(ui.dim('To change model: overarch config set model <id>'));
+            return;
+        }
+        const resolved = resolveModel(key);
+        if (!resolved) {
+            ui.warn(`Model '${key}' will be treated as custom '${key}'`);
+        }
+        await saveGlobalConfig({ defaultModel: key });
+        ui.success(`Default model set to: ${key}`);
+        return;
+    }
+    if (subcommand === 'accent') {
+        if (!key) {
+            console.log(`\nCurrent Accent: ${ui.accent(config.ui?.accentColor || 'cyan')}`);
+            console.log(ui.dim('Available: cyan, magenta, blue, green, yellow'));
+            return;
+        }
+        await saveGlobalConfig({ ui: { ...config.ui, accentColor: key } });
+        ui.setAccent(key);
+        ui.success(`Accent color updated to: ${ui.accent(key)}`);
+        return;
+    }
+    if (subcommand === 'avatar') {
+        if (!key) {
+            console.log(`\nCurrent Avatar: ${ui.accent(config.ui?.avatar || '◆')}`);
+            return;
+        }
+        await saveGlobalConfig({ ui: { ...config.ui, avatar: key } });
+        ui.setAvatar(key);
+        ui.success(`Avatar token updated to: ${ui.accent(key)}`);
+        return;
+    }
+    if (subcommand === 'permissions') {
+        console.log(`\nAuto-Approve Tiers:   ${config.permissions?.autoApprove?.join(', ') || 'none'}`);
+        console.log(`Require-Approval:      ${config.permissions?.requireApproval?.join(', ') || 'none'}`);
+        console.log(`Denied Tools:          ${config.permissions?.deny?.join(', ') || 'none'}`);
+        return;
+    }
+    // 2. Default List / Status View
+    if (!subcommand || subcommand === 'show' || subcommand === 'list') {
+        ui.statusCard('Overarch Configuration', {
+            'Config File': config.configPath || 'Defaults',
+            'Scope': config.isProjectConfig ? 'Project (.overarch/config.json)' : 'Global (~/.overarch/config.json)',
+            'Provider': config.activeProvider || 'anthropic',
+            'Model': config.defaultModel,
+            'Mode': config.mode === 'offline' ? ui.yellow('Offline') : 'Online',
+            'Accent Color': ui.accent(config.ui?.accentColor || 'cyan'),
+            'Avatar': ui.accent(config.ui?.avatar || '◆'),
+            'Ponytail Mode': config.ponytail || 'full',
+            'CCSS Mode': config.ccss || 'auto',
+            'Agent Mode': config.agentMode || 'approval',
+            'Auto-Approve Tiers': config.permissions?.autoApprove?.join(', ') || 'none'
+        });
+        console.log(ui.dim('\nTargets: provider, model, accent, avatar, permissions'));
+        console.log(ui.dim('Usage: overarch config <target> [value] | overarch config get <key> | overarch config set <key> <val>'));
+        return;
+    }
+    // 3. Get Key
+    if (subcommand === 'get') {
+        if (!key) {
+            ui.error('Key name required. Example: overarch config get defaultModel');
+            return;
+        }
+        const val = config[key] ?? config.ui?.[key];
+        if (val !== undefined) {
+            console.log(typeof val === 'object' ? JSON.stringify(val, null, 2) : String(val));
+        }
+        else {
+            ui.warn(`Key '${key}' not found in configuration.`);
+        }
+        return;
+    }
+    // 4. Set Key
+    if (subcommand === 'set') {
+        if (!key || value === undefined) {
+            ui.error('Key and value required. Example: overarch config set model gpt-4o');
+            return;
+        }
+        const updates = {};
+        if (key === 'model' || key === 'defaultModel') {
+            updates.defaultModel = value;
+        }
+        else if (key === 'provider' || key === 'activeProvider') {
+            updates.activeProvider = value.toLowerCase();
+        }
+        else if (key === 'accent' || key === 'accentColor') {
+            updates.ui = { ...config.ui, accentColor: value };
+            ui.setAccent(value);
+        }
+        else if (key === 'avatar') {
+            updates.ui = { ...config.ui, avatar: value };
+            ui.setAvatar(value);
+        }
+        else if (key === 'ponytail') {
+            updates.ponytail = value.toLowerCase();
+        }
+        else if (key === 'ccss') {
+            updates.ccss = value.toLowerCase();
+        }
+        else if (key === 'mode') {
+            updates.mode = value.toLowerCase() === 'offline' ? 'offline' : 'online';
+        }
+        else {
+            updates[key] = value;
+        }
+        await saveGlobalConfig(updates);
+        ui.success(`Updated ${key} = ${value}`);
+        return;
+    }
+    ui.error(`Unknown config action: ${subcommand}.`);
+}

package/dist/src/cli/commands/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctor(): Promise<void>;

package/dist/src/cli/commands/doctor.js

@@ -0,0 +1,217 @@
+import { execSync } from 'node:child_process';
+import * as ui from '../ui.js';
+import { loadConfig, getApiKey } from '../../config/index.js';
+import { resolveModel } from '../../providers/factory.js';
+import { ToolRegistry } from '../../tools/registry.js';
+import { petdexBridge } from '../../companion/petdex_bridge.js';
+import { policyEngine } from '../../security/policy.js';
+import fs from 'node:fs/promises';
+import * as syncFs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export async function doctor() {
+    ui.heading('Overarch Doctor Diagnostics');
+    console.log(ui.dim('Inspecting runtime, security policies, tool integrity, project context, and subsystems...\n'));
+    const issues = [];
+    // 1. Runtime & Environment (Node.js >= 20.0.0)
+    const nodeVersion = process.version;
+    const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+    if (majorVersion >= 20) {
+        ui.done(`Runtime: Node.js ${nodeVersion} (${process.platform} ${process.arch}, ESM & native APIs active)`);
+    }
+    else {
+        ui.fail(`Runtime: Node.js ${nodeVersion} (>= 20 required)`);
+        issues.push('Upgrade Node.js to v20 or higher.');
+    }
+    // 2. PATH Resolution & Global Command Integrity
+    try {
+        let resolvedCommand = '';
+        if (process.platform === 'win32') {
+            try {
+                const whereOutput = execSync('where.exe overarch 2>nul', { encoding: 'utf8' }).trim();
+                const lines = whereOutput.split('\r\n').map(l => l.trim()).filter(Boolean);
+                resolvedCommand = lines[0] || '';
+                if (lines.length > 1) {
+                    ui.done(`PATH: 'overarch' found in ${lines.length} locations (Primary: ${resolvedCommand})`);
+                }
+                else if (resolvedCommand) {
+                    ui.done(`PATH: 'overarch' command resolved cleanly at: ${resolvedCommand}`);
+                }
+                else {
+                    ui.warn(`PATH: 'overarch' not found via 'where.exe'`);
+                }
+            }
+            catch {
+                ui.done(`PATH: Standard environment active`);
+            }
+        }
+        else {
+            const whichOutput = execSync('which overarch 2>/dev/null', { encoding: 'utf8' }).trim();
+            ui.done(`PATH: 'overarch' resolved at: ${whichOutput}`);
+        }
+    }
+    catch {
+        ui.warn('PATH: Could not query active binary resolution');
+    }
+    // 3. Wrapper Script UTF-8 BOM Verification (preventing '@echo' syntax error in cmd.exe)
+    if (process.platform === 'win32') {
+        const candidateWrappers = [
+            path.join(os.homedir(), 'AppData', 'Local', 'Programs', 'Overarch', 'overarch.cmd'),
+            path.join(os.homedir(), 'AppData', 'Local', 'Microsoft', 'WindowsApps', 'overarch.cmd'),
+            path.join(os.homedir(), 'AppData', 'Roaming', 'npm', 'overarch.cmd'),
+        ];
+        let checkedWrappers = 0;
+        let hasBom = false;
+        for (const wrapper of candidateWrappers) {
+            if (syncFs.existsSync(wrapper)) {
+                checkedWrappers++;
+                try {
+                    const fd = syncFs.openSync(wrapper, 'r');
+                    const buffer = Buffer.alloc(3);
+                    syncFs.readSync(fd, buffer, 0, 3, 0);
+                    syncFs.closeSync(fd);
+                    if (buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf) {
+                        hasBom = true;
+                        ui.fail(`Wrapper Scripts: UTF-8 BOM detected in ${wrapper} (causes '@echo' command error)`);
+                        issues.push(`Re-save '${wrapper}' without BOM or re-run Overarch installer.`);
+                    }
+                }
+                catch { }
+            }
+        }
+        if (!hasBom && checkedWrappers > 0) {
+            ui.done(`Wrapper Scripts: Verified BOM-free across ${checkedWrappers} candidate shims (compatible with cmd.exe & PowerShell)`);
+        }
+        else if (checkedWrappers === 0) {
+            ui.done(`Wrapper Scripts: No external Windows shims to check (running locally)`);
+        }
+    }
+    // 4. Git Version Control
+    try {
+        const gitVersion = execSync('git --version', { encoding: 'utf8' }).trim();
+        ui.done(`Git: ${gitVersion}`);
+    }
+    catch {
+        ui.fail('Git: Not found in system PATH');
+        issues.push('Install Git or add it to your system PATH to enable version control and rollback features.');
+    }
+    // 5. Native Windows Desktop Compiler (if on Windows)
+    if (process.platform === 'win32') {
+        const cscCandidates = [
+            'C:\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319\\csc.exe',
+            'C:\\Windows\\Microsoft.NET\\Framework\\v4.0.30319\\csc.exe',
+        ];
+        const foundCsc = cscCandidates.find((p) => {
+            try {
+                return execSync(`where csc.exe 2>nul || (dir "${p}" 2>nul)`).length > 0;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (foundCsc) {
+            ui.done(`Windows Compiler: Native .NET C# compiler (csc.exe) detected`);
+        }
+        else {
+            ui.done(`Windows Compiler: Standard Windows system environment active`);
+        }
+    }
+    // 6. CCHCFAI Security & Policy Engine
+    const safeOnly = policyEngine.isSafeOnly();
+    if (safeOnly) {
+        ui.done(`CCHCFAI Policy: Active in SAFE-ONLY mode (all destructive shell & mutations blocked)`);
+    }
+    else {
+        ui.done(`CCHCFAI Policy: Active (Tier 0-3 tiered authority with human control gates)`);
+    }
+    // 7. File System Read / Write Permissions (Workspace & .overarch)
+    const cwd = process.cwd();
+    try {
+        const testFile = path.join(cwd, `.overarch_rw_test_${Date.now()}.tmp`);
+        await fs.writeFile(testFile, 'test', 'utf8');
+        await fs.unlink(testFile);
+        const overarchGlobal = path.join(os.homedir(), '.overarch');
+        if (!syncFs.existsSync(overarchGlobal)) {
+            await fs.mkdir(overarchGlobal, { recursive: true });
+        }
+        const testGlobal = path.join(overarchGlobal, `.rw_test_${Date.now()}.tmp`);
+        await fs.writeFile(testGlobal, 'test', 'utf8');
+        await fs.unlink(testGlobal);
+        ui.done(`Filesystem: Read & Write verified in workspace (${cwd}) and global (~/.overarch)`);
+    }
+    catch (err) {
+        ui.fail(`Filesystem: Write permission check failed: ${err.message}`);
+        issues.push(`Ensure directory permissions allow reading and writing.`);
+    }
+    // 8. Configuration & Auth
+    const config = await loadConfig();
+    ui.done(`Configuration: ${config.isProjectConfig ? 'Project (.overarch/config.json)' : 'Global (~/.overarch/config.json)'}`);
+    const activeModel = config.defaultModel;
+    const resolved = resolveModel(activeModel);
+    if (config.mode === 'offline' || resolved?.provider === 'none') {
+        ui.done(`Provider: Offline mode active (AI calls disabled)`);
+    }
+    else if (resolved) {
+        const key = getApiKey(resolved.provider);
+        if (key) {
+            ui.done(`Authentication: ${resolved.provider.toUpperCase()} API key detected`);
+        }
+        else {
+            ui.fail(`Authentication: Missing API key for provider '${resolved.provider}'`);
+            issues.push(`Set ${resolved.provider.toUpperCase()}_API_KEY in your environment or add to .env via \`/setup\`.`);
+        }
+        ui.done(`Model: ${resolved.displayName} (${resolved.provider}/${resolved.model})`);
+    }
+    else {
+        ui.fail(`Model: Unknown model '${activeModel}'`);
+        issues.push('Run `/setup` or `/config model <name>` to select a valid model.');
+    }
+    // 9. .overarch Project Subsystem & Audit Log
+    const overarchDir = path.join(cwd, '.overarch');
+    try {
+        await fs.access(overarchDir);
+        const subFiles = await fs.readdir(overarchDir);
+        ui.done(`.overarch Subsystem: Initialized (${subFiles.length} items: ${subFiles.join(', ')})`);
+    }
+    catch {
+        ui.warn(`.overarch Subsystem: Not initialized in current directory`);
+        issues.push('Run `overarch init` or `/init` in the REPL to initialize project context.');
+    }
+    // 10. Tool Registry (including web_search)
+    const registry = ToolRegistry.createDefault();
+    const tools = registry.list();
+    const hasWebSearch = tools.some((t) => t.name === 'web_search');
+    if (hasWebSearch) {
+        ui.done(`Tools: ${tools.length} registered (including native web_search & precision file patchers)`);
+    }
+    else {
+        ui.warn(`Tools: ${tools.length} registered`);
+    }
+    // 11. Companion Health & Petdex Bridge
+    const bridgeStatus = petdexBridge.getStatus();
+    let companionExeFound = false;
+    if (process.platform === 'win32') {
+        const compCandidates = [
+            path.join(cwd, 'dist-desktop', 'OverarchCompanion.exe'),
+            path.join(os.homedir(), 'AppData', 'Local', 'Programs', 'Overarch', 'OverarchCompanion.exe'),
+        ];
+        companionExeFound = compCandidates.some(c => syncFs.existsSync(c));
+    }
+    if (bridgeStatus.running) {
+        ui.done(`Companion Health: Active and listening on port ${bridgeStatus.port} (Companion binary: ${companionExeFound ? 'Available' : 'Standby'})`);
+    }
+    else {
+        ui.done(`Companion Health: Standby (Bridge ready, companion executable: ${companionExeFound ? 'Available' : 'Ready'})`);
+    }
+    console.log();
+    if (issues.length === 0) {
+        ui.success('All systems healthy. Overarch CLI is ready for autonomous software engineering.');
+    }
+    else {
+        ui.warn(`Identified ${issues.length} item(s) requiring attention:`);
+        issues.forEach((iss, idx) => {
+            console.log(`  ${idx + 1}. ${iss}`);
+        });
+        console.log(`\n${ui.dim('Run /setup to re-run the configuration wizard.')}`);
+    }
+}

package/dist/src/cli/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function init(): Promise<void>;

package/dist/src/cli/commands/init.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import * as ui from '../ui.js';
+import { DEFAULT_CONFIG } from '../../config/index.js';
+export async function init() {
+    ui.heading('Initialize Overarch Project Context');
+    const cwd = process.cwd();
+    const projectConfigDir = path.join(cwd, '.overarch');
+    // 1. Detect project characteristics
+    const detectedStacks = [];
+    let testCommand = '';
+    let buildCommand = '';
+    try {
+        const pkg = JSON.parse(await fs.readFile(path.join(cwd, 'package.json'), 'utf8'));
+        detectedStacks.push(`Node.js (${pkg.name || 'unnamed'})`);
+        if (pkg.scripts?.test)
+            testCommand = 'npm test';
+        if (pkg.scripts?.build)
+            buildCommand = 'npm run build';
+        if (pkg.dependencies?.typescript || pkg.devDependencies?.typescript) {
+            detectedStacks.push('TypeScript');
+        }
+        if (pkg.dependencies?.react || pkg.devDependencies?.react) {
+            detectedStacks.push('React');
+        }
+    }
+    catch { }
+    try {
+        await fs.readFile(path.join(cwd, 'Cargo.toml'), 'utf8');
+        detectedStacks.push('Rust');
+        if (!testCommand)
+            testCommand = 'cargo test';
+        if (!buildCommand)
+            buildCommand = 'cargo build';
+    }
+    catch { }
+    try {
+        await fs.readFile(path.join(cwd, 'pyproject.toml'), 'utf8');
+        detectedStacks.push('Python');
+        if (!testCommand)
+            testCommand = 'pytest';
+    }
+    catch {
+        try {
+            await fs.readFile(path.join(cwd, 'requirements.txt'), 'utf8');
+            detectedStacks.push('Python');
+        }
+        catch { }
+    }
+    try {
+        await fs.readFile(path.join(cwd, 'go.mod'), 'utf8');
+        detectedStacks.push('Go');
+        if (!testCommand)
+            testCommand = 'go test ./...';
+        if (!buildCommand)
+            buildCommand = 'go build ./...';
+    }
+    catch { }
+    // 2. Discover root files & directories
+    const ignoreList = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.turbo', '.cache']);
+    const files = await fs.readdir(cwd, { withFileTypes: true });
+    const keyDirs = [];
+    for (const f of files) {
+        if (ignoreList.has(f.name))
+            continue;
+        if (f.isDirectory())
+            keyDirs.push(f.name);
+    }
+    // 3. Create .overarch structure
+    await fs.mkdir(projectConfigDir, { recursive: true });
+    await fs.mkdir(path.join(projectConfigDir, 'sessions'), { recursive: true });
+    await fs.mkdir(path.join(projectConfigDir, 'cache'), { recursive: true });
+    // config.json
+    const configPath = path.join(projectConfigDir, 'config.json');
+    try {
+        await fs.access(configPath);
+    }
+    catch {
+        const projectConfig = {
+            project: {
+                ...DEFAULT_CONFIG.project,
+                include: keyDirs,
+            }
+        };
+        await fs.writeFile(configPath, JSON.stringify(projectConfig, null, 2), 'utf8');
+    }
+    // instructions.md
+    const instructionsPath = path.join(projectConfigDir, 'instructions.md');
+    try {
+        await fs.access(instructionsPath);
+    }
+    catch {
+        let template = `# ${path.basename(cwd)} — Architecture Guidelines\n\n`;
+        template += `## Tech Stack\n${detectedStacks.length > 0 ? detectedStacks.map(s => `- ${s}`).join('\n') : '- General'}\n\n`;
+        if (buildCommand)
+            template += `## Build Command\n\`${buildCommand}\`\n\n`;
+        if (testCommand)
+            template += `## Test Command\n\`${testCommand}\`\n\n`;
+        template += `## Development Principles\n`;
+        template += `- Prefer small, verifiable changes\n`;
+        template += `- Always run tests before declaring tasks complete\n`;
+        template += `- Follow existing styling and patterns\n`;
+        await fs.writeFile(instructionsPath, template, 'utf8');
+    }
+    // memory.md
+    const memoryPath = path.join(projectConfigDir, 'memory.md');
+    try {
+        await fs.access(memoryPath);
+    }
+    catch {
+        const memTemplate = `# Project Memory\n\n- [${new Date().toISOString().slice(0, 10)}] Initialized Overarch project context\n`;
+        await fs.writeFile(memoryPath, memTemplate, 'utf8');
+    }
+    // .gitignore
+    const gitignorePath = path.join(projectConfigDir, '.gitignore');
+    await fs.writeFile(gitignorePath, 'sessions/\ncache/\n*.log\n*.env\nstate.json\n', 'utf8');
+    // context.json
+    const contextPath = path.join(projectConfigDir, 'context.json');
+    const contextIndex = {
+        initializedAt: new Date().toISOString(),
+        stacks: detectedStacks,
+        keyDirectories: keyDirs,
+        buildCommand,
+        testCommand
+    };
+    await fs.writeFile(contextPath, JSON.stringify(contextIndex, null, 2), 'utf8');
+    console.log();
+    ui.done(`Detected Stack: ${detectedStacks.length > 0 ? detectedStacks.join(', ') : 'Generic'}`);
+    ui.done(`Discovered Directories: ${keyDirs.join(', ') || 'root'}`);
+    ui.done(`Initialized .overarch subsystem in ${projectConfigDir}`);
+    ui.done(`Created project instructions template at .overarch/instructions.md`);
+    ui.done(`Created project memory ledger at .overarch/memory.md`);
+    console.log(`\n${ui.accent(ui.getAvatar())} Project context established. Overarch is now tailored to this repository.`);
+}

package/dist/src/cli/commands/memory.d.ts

@@ -0,0 +1,2 @@
+export declare function handleMemoryCommand(subcommand?: string, arg1?: string, arg2?: string): Promise<void>;
+export declare function handleLearnCommand(lessonText?: string): Promise<void>;