archbyte 0.2.9 → 0.3.0

package/dist/agents/pipeline/agents/component-identifier.js

@@ -3,10 +3,19 @@
 import { extractJSON } from "../response-parser.js";
 import { getPrompt } from "../../prompts.js";
 import "../../prompt-data.js";
-function formatFileTree(ctx) {
+function formatFileTree(ctx, affectedPaths) {
     // Show directories + key files only (not all 1000+ files) to stay within context limits
     const lines = [];
-    const MAX_LINES = 300;
+    const MAX_LINES = affectedPaths ? 150 : 300;
+    function isAffectedSubtree(dirPath) {
+        if (!affectedPaths)
+            return true;
+        for (const p of affectedPaths) {
+            if (p.startsWith(dirPath + "/") || dirPath.startsWith(p + "/") || dirPath === p)
+                return true;
+        }
+        return false;
+    }
     function walk(entries, indent) {
         for (const e of entries) {
             if (lines.length >= MAX_LINES)
@@ -14,6 +23,11 @@ function formatFileTree(ctx) {
             if (e.type === "directory") {
                 const fileCount = e.children?.filter((c) => c.type === "file").length ?? 0;
                 const dirCount = e.children?.filter((c) => c.type === "directory").length ?? 0;
+                if (affectedPaths && indent >= 1 && !isAffectedSubtree(e.path)) {
+                    // Collapse unchanged directories
+                    lines.push(`${"  ".repeat(indent)}${e.path}/ ... (${fileCount} files, unchanged)`);
+                    continue;
+                }
                 lines.push(`${"  ".repeat(indent)}${e.path}/ (${fileCount} files, ${dirCount} dirs)`);
                 if (e.children)
                     walk(e.children, indent + 1);
@@ -48,8 +62,49 @@ export const componentIdentifier = {
     buildPrompt(ctx, priorResults) {
         const system = getPrompt("pipeline/component-identifier");
         const incremental = priorResults?.["__incremental__"];
-        const fileTree = formatFileTree(ctx);
-        const configs = formatConfigs(ctx);
+        // Build set of affected paths for tree filtering
+        let affectedPaths;
+        if (incremental) {
+            affectedPaths = new Set();
+            // Include paths of affected components
+            for (const compId of incremental.affectedComponents) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedPaths.add(comp.path);
+            }
+            // Include paths of neighbor components
+            for (const compId of incremental.neighborComponents) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedPaths.add(comp.path);
+            }
+            // Include directories of changed files
+            for (const f of incremental.changedFiles) {
+                const dir = f.includes("/") ? f.substring(0, f.lastIndexOf("/")) : ".";
+                affectedPaths.add(dir);
+            }
+        }
+        const fileTree = formatFileTree(ctx, affectedPaths);
+        // Filter configs: in incremental mode, only include configs from affected dirs + root configs
+        let configs;
+        if (incremental && affectedPaths) {
+            const filteredConfigs = ctx.codeSamples.configFiles.filter((cf) => {
+                const dir = cf.path.includes("/") ? cf.path.substring(0, cf.path.lastIndexOf("/")) : ".";
+                // Always include root configs
+                if (!cf.path.includes("/"))
+                    return true;
+                // Include configs from affected directories
+                for (const p of affectedPaths) {
+                    if (dir.startsWith(p) || p.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+            configs = filteredConfigs.map((cf) => `--- ${cf.path} ---\n${cf.content}`).join("\n\n");
+        }
+        else {
+            configs = formatConfigs(ctx);
+        }
         const structureInfo = [
             `Project: ${ctx.structure.projectName || "(unknown)"}`,
             `Language: ${ctx.structure.language}`,
@@ -62,9 +117,13 @@ export const componentIdentifier = {
         const docNotes = ctx.docs.architectureNotes.length > 0
             ? `\n\nArchitecture notes from docs:\n${ctx.docs.architectureNotes.join("\n")}`
             : "";
-        const dockerInfo = ctx.infra.docker.composeFile
-            ? `\n\nDocker Compose services:\n${ctx.infra.docker.services.map((s) => `- ${s.name}${s.image ? ` (image: ${s.image})` : ""}${s.buildContext ? ` (build: ${s.buildContext})` : ""}${s.dependsOn?.length ? ` depends_on: ${s.dependsOn.join(", ")}` : ""}`).join("\n")}`
-            : "";
+        // In incremental mode, only include Docker info if infra files changed
+        let dockerInfo = "";
+        if (ctx.infra.docker.composeFile) {
+            if (!incremental || incremental.categories.infraFiles.length > 0) {
+                dockerInfo = `\n\nDocker Compose services:\n${ctx.infra.docker.services.map((s) => `- ${s.name}${s.image ? ` (image: ${s.image})` : ""}${s.buildContext ? ` (build: ${s.buildContext})` : ""}${s.dependsOn?.length ? ` depends_on: ${s.dependsOn.join(", ")}` : ""}`).join("\n")}`;
+            }
+        }
         let incrementalInfo = "";
         if (incremental) {
             const existing = Object.entries(incremental.existingSpec.components)
@@ -76,7 +135,7 @@ ${existing}
 Changed files: ${incremental.changedFiles.join(", ")}
 Affected components: ${incremental.affectedComponents.length > 0 ? incremental.affectedComponents.join(", ") : "none (check for new components)"}
 
-IMPORTANT: Return ALL components — both existing unaffected ones AND updated/new ones. Only re-analyze components whose paths overlap with the changed files.`;
+IMPORTANT: Return ALL components — both existing unaffected ones AND updated/new ones. Focus: re-evaluate components in [${[...new Set([...incremental.affectedComponents, ...incremental.neighborComponents])].join(", ")}]. Return other components as-is.`;
         }
         const user = `Analyze this project and identify ALL architecturally significant components.
 

package/dist/agents/pipeline/agents/connection-mapper.js

@@ -47,10 +47,36 @@ export const connectionMapper = {
                 parts.push(`- ${ar.method} ${ar.path} (${ar.handlerFile})`);
             }
         }
-        // Import map
-        const importEntries = Object.entries(ctx.codeSamples.importMap);
+        // Import map — filter to affected + neighbor component dirs in incremental mode
+        const incremental = priorResults?.["__incremental__"];
+        let affectedDirs;
+        if (incremental) {
+            affectedDirs = new Set();
+            for (const compId of [...incremental.affectedComponents, ...incremental.neighborComponents]) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedDirs.add(comp.path);
+            }
+            for (const f of incremental.changedFiles) {
+                const dir = f.includes("/") ? f.substring(0, f.lastIndexOf("/")) : ".";
+                affectedDirs.add(dir);
+            }
+        }
+        let importEntries = Object.entries(ctx.codeSamples.importMap);
+        if (affectedDirs && affectedDirs.size > 0) {
+            importEntries = importEntries.filter(([file]) => {
+                const dir = file.includes("/") ? file.substring(0, file.lastIndexOf("/")) : ".";
+                for (const ad of affectedDirs) {
+                    if (dir.startsWith(ad) || ad.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+        }
         if (importEntries.length > 0) {
-            parts.push(`\n## Import Graph (${importEntries.length} files)`);
+            const totalEntries = Object.keys(ctx.codeSamples.importMap).length;
+            const label = affectedDirs ? `${importEntries.length} of ${totalEntries} files, filtered to affected dirs` : `${totalEntries} files`;
+            parts.push(`\n## Import Graph (${label})`);
             // Summarize by directory to keep it concise
             const dirImports = {};
             for (const [file, imports] of importEntries) {
@@ -69,8 +95,8 @@ export const connectionMapper = {
                 }
             }
         }
-        // Docker depends_on
-        if (ctx.infra.docker.composeFile) {
+        // Docker depends_on — only if infra changed (or full scan)
+        if (ctx.infra.docker.composeFile && (!incremental || incremental.categories.infraFiles.length > 0)) {
             const deps = ctx.infra.docker.services
                 .filter((s) => s.dependsOn?.length)
                 .map((s) => `${s.name} → ${s.dependsOn.join(", ")}`);
@@ -78,15 +104,14 @@ export const connectionMapper = {
                 parts.push(`\n## Docker depends_on\n${deps.join("\n")}`);
             }
         }
-        // Kubernetes resources
-        if (ctx.infra.kubernetes.resources.length > 0) {
+        // Kubernetes resources — only if infra changed (or full scan)
+        if (ctx.infra.kubernetes.resources.length > 0 && (!incremental || incremental.categories.infraFiles.length > 0)) {
             parts.push("\n## Kubernetes Resources");
             for (const r of ctx.infra.kubernetes.resources) {
                 parts.push(`- ${r.kind}: ${r.name}${r.namespace ? ` (ns=${r.namespace})` : ""}`);
             }
         }
         // Incremental context
-        const incremental = priorResults?.["__incremental__"];
         if (incremental) {
             const existingConns = incremental.existingSpec.connections
                 .map((c) => `- ${c.from} → ${c.to} (${c.type}${c.async ? ", async" : ""}): ${c.description}`)

package/dist/agents/pipeline/agents/flow-detector.js

@@ -11,6 +11,20 @@ export const flowDetector = {
     buildPrompt(ctx, priorResults) {
         const system = getPrompt("pipeline/flow-detector");
         const incremental = priorResults?.["__incremental__"];
+        // Build set of affected directories for filtering
+        let affectedDirs;
+        if (incremental) {
+            affectedDirs = new Set();
+            for (const compId of [...incremental.affectedComponents, ...incremental.neighborComponents]) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedDirs.add(comp.path);
+            }
+            for (const f of incremental.changedFiles) {
+                const dir = f.includes("/") ? f.substring(0, f.lastIndexOf("/")) : ".";
+                affectedDirs.add(dir);
+            }
+        }
         const parts = [];
         // Event patterns from static scanner
         if (ctx.events.hasEDA) {
@@ -18,8 +32,23 @@ export const flowDetector = {
             for (const p of ctx.events.patterns) {
                 parts.push(`  Technology: ${p.technology} (dep: ${p.dependency})`);
             }
-            parts.push("\nEvent occurrences in code:");
-            for (const e of ctx.events.events.slice(0, 30)) {
+            // Filter events to affected directories in incremental mode
+            let events = ctx.events.events;
+            if (affectedDirs && affectedDirs.size > 0) {
+                events = events.filter((e) => {
+                    const dir = e.file.includes("/") ? e.file.substring(0, e.file.lastIndexOf("/")) : ".";
+                    for (const ad of affectedDirs) {
+                        if (dir.startsWith(ad) || ad.startsWith(dir))
+                            return true;
+                    }
+                    return false;
+                });
+                parts.push(`\nEvent occurrences in affected files (${events.length} of ${ctx.events.events.length} total):`);
+            }
+            else {
+                parts.push("\nEvent occurrences in code:");
+            }
+            for (const e of events.slice(0, 30)) {
                 parts.push(`  [${e.type}] ${e.file}: ${e.pattern}`);
             }
         }
@@ -33,24 +62,48 @@ export const flowDetector = {
                 parts.push(`  ${ep.method} ${ep.path} — ${ep.description}`);
             }
         }
-        // Route file samples
-        const routeSamples = ctx.codeSamples.samples.filter((s) => s.category === "route-file");
+        // Route file samples — filter to affected directories in incremental mode
+        let routeSamples = ctx.codeSamples.samples.filter((s) => s.category === "route-file");
+        if (affectedDirs && affectedDirs.size > 0) {
+            const filtered = routeSamples.filter((s) => {
+                const dir = s.path.includes("/") ? s.path.substring(0, s.path.lastIndexOf("/")) : ".";
+                for (const ad of affectedDirs) {
+                    if (dir.startsWith(ad) || ad.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+            if (filtered.length > 0)
+                routeSamples = filtered;
+        }
         if (routeSamples.length > 0) {
             parts.push("\nRoute file excerpts:");
             for (const s of routeSamples.slice(0, 5)) {
                 parts.push(`\n--- ${s.path} ---\n${s.excerpt}`);
             }
         }
-        // Entry points for context
-        const entrySamples = ctx.codeSamples.samples.filter((s) => s.category === "entry-point");
+        // Entry points — filter to affected directories in incremental mode
+        let entrySamples = ctx.codeSamples.samples.filter((s) => s.category === "entry-point");
+        if (affectedDirs && affectedDirs.size > 0) {
+            const filtered = entrySamples.filter((s) => {
+                const dir = s.path.includes("/") ? s.path.substring(0, s.path.lastIndexOf("/")) : ".";
+                for (const ad of affectedDirs) {
+                    if (dir.startsWith(ad) || ad.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+            if (filtered.length > 0)
+                entrySamples = filtered;
+        }
         if (entrySamples.length > 0) {
             parts.push("\nEntry point excerpts:");
             for (const s of entrySamples.slice(0, 3)) {
                 parts.push(`\n--- ${s.path} ---\n${s.excerpt}`);
             }
         }
-        // Docker info for queue/broker identification
-        if (ctx.infra.docker.composeFile) {
+        // Docker info for queue/broker identification — only if event-related files changed
+        if (ctx.infra.docker.composeFile && (!incremental || incremental.categories.eventFiles.length > 0 || incremental.categories.infraFiles.length > 0)) {
             const queueServices = ctx.infra.docker.services.filter((s) => {
                 const img = (s.image ?? "").toLowerCase();
                 return img.includes("rabbit") || img.includes("kafka") || img.includes("redis") ||

package/dist/agents/pipeline/agents/service-describer.js

@@ -11,6 +11,22 @@ export const serviceDescriber = {
     buildPrompt(ctx, priorResults) {
         const system = getPrompt("pipeline/service-describer");
         const incremental = priorResults?.["__incremental__"];
+        // Build affected dirs for filtering
+        let affectedDirs;
+        if (incremental) {
+            affectedDirs = new Set();
+            for (const compId of [...incremental.affectedComponents, ...incremental.neighborComponents]) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedDirs.add(comp.path);
+            }
+            for (const f of incremental.changedFiles) {
+                const dir = f.includes("/") ? f.substring(0, f.lastIndexOf("/")) : ".";
+                affectedDirs.add(dir);
+            }
+        }
+        const hasInfraChanges = incremental ? incremental.categories.infraFiles.length > 0 : true;
+        const hasConfigChanges = incremental ? incremental.categories.configFiles.length > 0 : true;
         const parts = [];
         // Structure info
         parts.push(`Project: ${ctx.structure.projectName || "(unknown)"}`);
@@ -24,8 +40,8 @@ export const serviceDescriber = {
         if (ctx.docs.externalDependencies.length > 0) {
             parts.push(`\nExternal dependencies mentioned: ${ctx.docs.externalDependencies.join(", ")}`);
         }
-        // Docker services
-        if (ctx.infra.docker.composeFile) {
+        // Docker services — only include if infra/config files changed (or full scan)
+        if (ctx.infra.docker.composeFile && (hasInfraChanges || hasConfigChanges)) {
             const svcInfo = ctx.infra.docker.services.map((s) => {
                 const details = [s.name];
                 if (s.image)
@@ -40,22 +56,34 @@ export const serviceDescriber = {
             });
             parts.push(`\nDocker services:\n${svcInfo.join("\n")}`);
         }
-        // Env vars
-        if (ctx.envs.environments.length > 0) {
+        // Env vars — only include if infra/config files changed (or full scan)
+        if (ctx.envs.environments.length > 0 && (hasInfraChanges || hasConfigChanges)) {
             for (const env of ctx.envs.environments) {
                 parts.push(`\nEnv file "${env.name}" variables: ${env.variables.join(", ")}`);
             }
         }
-        // Code samples (entry points)
-        const entrySamples = ctx.codeSamples.samples.filter((s) => s.category === "entry-point");
+        // Code samples (entry points) — filter to affected dirs in incremental mode
+        let entrySamples = ctx.codeSamples.samples.filter((s) => s.category === "entry-point");
+        if (affectedDirs && affectedDirs.size > 0) {
+            const filtered = entrySamples.filter((s) => {
+                const dir = s.path.includes("/") ? s.path.substring(0, s.path.lastIndexOf("/")) : ".";
+                for (const ad of affectedDirs) {
+                    if (dir.startsWith(ad) || ad.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+            if (filtered.length > 0)
+                entrySamples = filtered;
+        }
         if (entrySamples.length > 0) {
             parts.push("\nEntry point excerpts:");
             for (const s of entrySamples.slice(0, 5)) {
                 parts.push(`\n--- ${s.path} ---\n${s.excerpt}`);
             }
         }
-        // Cloud info
-        if (ctx.infra.cloud.provider) {
+        // Cloud info — only if infra changed (or full scan)
+        if (ctx.infra.cloud.provider && hasInfraChanges) {
             parts.push(`\nCloud: ${ctx.infra.cloud.provider}, services: ${ctx.infra.cloud.services.join(", ")}`);
         }
         // Incremental context

package/dist/agents/pipeline/agents/validator.js

@@ -10,15 +10,36 @@ export const validator = {
     phase: "sequential",
     buildPrompt(ctx, priorResults) {
         const system = getPrompt("pipeline/validator");
+        const incremental = priorResults?.["__incremental__"];
+        // Build set of relevant component IDs for filtering
+        let relevantComponents;
+        if (incremental) {
+            relevantComponents = new Set([...incremental.affectedComponents, ...incremental.neighborComponents]);
+        }
         const parts = [];
-        // Components
+        // Components — in incremental mode, show affected + neighbors in full, others as summary
         const components = priorResults?.["component-identifier"];
         if (components?.components) {
-            parts.push("## Components");
-            for (const c of components.components) {
-                parts.push(`- ${c.id}: ${c.name} (type=${c.type}, layer=${c.layer}, path=${c.path})`);
-                parts.push(`  description: ${c.description || "(none)"}`);
-                parts.push(`  tech: [${(c.technologies || []).join(", ")}]`);
+            if (relevantComponents && relevantComponents.size > 0) {
+                const relevant = components.components.filter((c) => relevantComponents.has(c.id));
+                const others = components.components.length - relevant.length;
+                parts.push("## Components (affected + neighbors)");
+                for (const c of relevant) {
+                    parts.push(`- ${c.id}: ${c.name} (type=${c.type}, layer=${c.layer}, path=${c.path})`);
+                    parts.push(`  description: ${c.description || "(none)"}`);
+                    parts.push(`  tech: [${(c.technologies || []).join(", ")}]`);
+                }
+                if (others > 0) {
+                    parts.push(`\n(${others} other unchanged components omitted)`);
+                }
+            }
+            else {
+                parts.push("## Components");
+                for (const c of components.components) {
+                    parts.push(`- ${c.id}: ${c.name} (type=${c.type}, layer=${c.layer}, path=${c.path})`);
+                    parts.push(`  description: ${c.description || "(none)"}`);
+                    parts.push(`  tech: [${(c.technologies || []).join(", ")}]`);
+                }
             }
         }
         // Services
@@ -35,11 +56,19 @@ export const validator = {
                 parts.push(`- ${svc.id}: ${svc.name} (${svc.type}) — ${svc.description}`);
             }
         }
-        // Connections
+        // Connections — in incremental mode, only show connections involving affected/neighbor components
         const connections = priorResults?.["connection-mapper"];
         if (connections?.connections) {
-            parts.push("\n## Connections");
-            for (const c of connections.connections) {
+            let conns = connections.connections;
+            if (relevantComponents && relevantComponents.size > 0) {
+                conns = conns.filter((c) => relevantComponents.has(c.from) || relevantComponents.has(c.to));
+                const omitted = connections.connections.length - conns.length;
+                parts.push(`\n## Connections (involving affected components${omitted > 0 ? `, ${omitted} others omitted` : ""})`);
+            }
+            else {
+                parts.push("\n## Connections");
+            }
+            for (const c of conns) {
                 parts.push(`- ${c.from} → ${c.to} (${c.type}) ${c.async ? "[async]" : ""}: ${c.description}`);
             }
         }

package/dist/agents/pipeline/index.d.ts

@@ -11,4 +11,5 @@ export declare function runPipeline(ctx: StaticContext, provider: LLMProvider, c
         input: number;
         output: number;
     };
+    skippedAgents?: string[];
 }>;

package/dist/agents/pipeline/index.js

@@ -15,6 +15,79 @@ function isAuthError(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return /401|authentication_error|invalid.*api.?key|unauthorized|invalid.*key/i.test(msg);
 }
+/**
+ * Determine if an agent can be skipped based on what changed.
+ * Returns a skip reason string if skippable, or null if the agent must run.
+ */
+function shouldSkipAgent(agentId, inc) {
+    // Never skip if there are unmapped files — potential new components
+    if (inc.hasUnmappedFiles)
+        return null;
+    const cat = inc.categories;
+    const hasInfra = cat.infraFiles.length > 0;
+    const hasConfig = cat.configFiles.length > 0;
+    const hasEntryPoints = cat.entryPoints.length > 0;
+    const hasRoutes = cat.routeFiles.length > 0;
+    const hasEvents = cat.eventFiles.length > 0;
+    switch (agentId) {
+        case "service-describer":
+            // Skip when no infra/config/entry-point changes
+            if (!hasInfra && !hasConfig && !hasEntryPoints) {
+                return "no infra/config/entry-point changes";
+            }
+            return null;
+        case "flow-detector":
+            // Skip when no route/event/entry-point changes
+            if (!hasRoutes && !hasEvents && !hasEntryPoints) {
+                return "no route/event/entry-point changes";
+            }
+            return null;
+        case "validator":
+            // Skip when ≤1 affected component and no infra changes
+            if (inc.affectedComponents.length <= 1 && !hasInfra) {
+                return `only ${inc.affectedComponents.length} component affected, no infra changes`;
+            }
+            return null;
+        // component-identifier and connection-mapper never skip
+        default:
+            return null;
+    }
+}
+/** Build fallback data for a skipped agent from existing spec */
+function getFallbackData(agentId, inc) {
+    switch (agentId) {
+        case "service-describer": {
+            const dbs = Object.entries(inc.existingSpec.databases).map(([id, d]) => ({
+                id, name: d.name, type: d.type, description: d.description, usedBy: [],
+            }));
+            const exts = Object.entries(inc.existingSpec["external-services"]).map(([id, s]) => ({
+                id, name: s.name, type: s.type, description: s.description, usedBy: [],
+            }));
+            return {
+                projectDescription: "",
+                primaryLanguage: "",
+                databases: dbs,
+                externalServices: exts,
+            };
+        }
+        case "flow-detector":
+            return {
+                eventConnections: [],
+                apiRoutes: [],
+            };
+        case "validator":
+            return {
+                componentTypeCorrections: {},
+                componentDescriptions: {},
+                addedConnections: [],
+                removedConnectionKeys: [],
+                confidence: 0.8,
+                issues: [],
+            };
+        default:
+            return null;
+    }
+}
 /**
  * Run the multi-agent pipeline: 3 parallel fast agents → 2 sequential agents.
  * Each agent gets a single chat() call with pre-collected static context.
@@ -22,6 +95,7 @@ function isAuthError(err) {
 export async function runPipeline(ctx, provider, config, onProgress, incrementalContext) {
     const agentResults = {};
     const agentMeta = [];
+    const skippedAgents = [];
     // Pass incremental context to agents via priorResults
     if (incrementalContext) {
         agentResults["__incremental__"] = incrementalContext;
@@ -30,10 +104,27 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
     onProgress?.(`Phase 1: Running ${PARALLEL_AGENTS.length} agents in parallel...`);
     // Pass agentResults to parallel agents too (contains __incremental__ if set)
     const parallelPrior = incrementalContext ? agentResults : undefined;
-    const parallelResults = await Promise.allSettled(PARALLEL_AGENTS.map((agent) => runAgent(agent, ctx, provider, config, parallelPrior, onProgress)));
+    // Check for agent skipping
+    const parallelTasks = PARALLEL_AGENTS.map((agent) => ({
+        agent,
+        skipReason: incrementalContext ? shouldSkipAgent(agent.id, incrementalContext) : null,
+    }));
+    const parallelResults = await Promise.allSettled(parallelTasks.map(({ agent, skipReason }) => {
+        if (skipReason) {
+            // Skip this agent — use fallback data
+            skippedAgents.push(agent.id);
+            onProgress?.(`  ${agent.name}: skipped (${skipReason})`);
+            const fallback = getFallbackData(agent.id, incrementalContext);
+            agentResults[agent.id] = fallback;
+            return Promise.resolve(null);
+        }
+        return runAgent(agent, ctx, provider, config, parallelPrior, onProgress);
+    }));
     let authFailed = false;
-    for (let i = 0; i < PARALLEL_AGENTS.length; i++) {
-        const agent = PARALLEL_AGENTS[i];
+    for (let i = 0; i < parallelTasks.length; i++) {
+        const { agent, skipReason } = parallelTasks[i];
+        if (skipReason)
+            continue; // Already handled
         const result = parallelResults[i];
         if (result.status === "fulfilled" && result.value) {
             agentResults[agent.id] = result.value.data;
@@ -55,6 +146,15 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
     // === Phase 2: Sequential agents ===
     onProgress?.(`Phase 2: Running ${SEQUENTIAL_AGENTS.length} agents sequentially...`);
     for (const agent of SEQUENTIAL_AGENTS) {
+        // Check for agent skipping
+        const skipReason = incrementalContext ? shouldSkipAgent(agent.id, incrementalContext) : null;
+        if (skipReason) {
+            skippedAgents.push(agent.id);
+            onProgress?.(`  ${agent.name}: skipped (${skipReason})`);
+            const fallback = getFallbackData(agent.id, incrementalContext);
+            agentResults[agent.id] = fallback;
+            continue;
+        }
         try {
             const result = await runAgent(agent, ctx, provider, config, agentResults, onProgress);
             if (result) {
@@ -82,13 +182,29 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
     if (merged.validation.repairs.length > 0) {
         onProgress?.(`Applied ${merged.validation.repairs.length} deterministic repair(s)`);
     }
-    // Log token usage
+    // Log per-agent + total token usage
     const totalInput = agentMeta.reduce((s, a) => s + (a.tokenUsage?.input ?? 0), 0);
     const totalOutput = agentMeta.reduce((s, a) => s + (a.tokenUsage?.output ?? 0), 0);
-    if (totalInput > 0) {
-        onProgress?.(`Token usage: ${totalInput} in / ${totalOutput} out`);
+    if (totalInput > 0 || skippedAgents.length > 0) {
+        // Log to stderr so progress bar doesn't clobber it
+        console.error("\n  Token usage breakdown:");
+        for (const a of agentMeta) {
+            const inp = a.tokenUsage?.input ?? 0;
+            const out = a.tokenUsage?.output ?? 0;
+            const dur = (a.duration / 1000).toFixed(1);
+            console.error(`    ${a.agentId.padEnd(22)} ${String(inp).padStart(6)} in  ${String(out).padStart(6)} out  ${dur}s`);
+        }
+        for (const id of skippedAgents) {
+            console.error(`    ${id.padEnd(22)}      0 in       0 out  SKIPPED`);
+        }
+        console.error(`    ${"TOTAL".padEnd(22)} ${String(totalInput).padStart(6)} in  ${String(totalOutput).padStart(6)} out`);
+        if (skippedAgents.length > 0) {
+            console.error(`    Skipped ${skippedAgents.length} agent(s): ${skippedAgents.join(", ")}`);
+        }
+        console.error();
+        onProgress?.(`Token usage: ${totalInput} in / ${totalOutput} out${skippedAgents.length > 0 ? ` (${skippedAgents.length} skipped)` : ""}`);
     }
-    return { ...merged, tokenUsage: { input: totalInput, output: totalOutput } };
+    return { ...merged, tokenUsage: { input: totalInput, output: totalOutput }, skippedAgents: skippedAgents.length > 0 ? skippedAgents : undefined };
 }
 // Agents that produce large structured output (lists of components/connections) need more tokens
 const MAX_TOKENS = {

package/dist/agents/pipeline/types.d.ts

@@ -82,6 +82,14 @@ export interface ValidatorOutput {
     confidence: number;
     issues: string[];
 }
+export interface CategorizedChanges {
+    entryPoints: string[];
+    routeFiles: string[];
+    configFiles: string[];
+    infraFiles: string[];
+    eventFiles: string[];
+    sourceFiles: string[];
+}
 export interface IncrementalContext {
     existingSpec: {
         components: Record<string, {
@@ -123,6 +131,9 @@ export interface IncrementalContext {
     };
     changedFiles: string[];
     affectedComponents: string[];
+    categories: CategorizedChanges;
+    neighborComponents: string[];
+    hasUnmappedFiles: boolean;
 }
 export interface PipelineAgentResult {
     agentId: string;

package/dist/agents/providers/openai.js

@@ -7,12 +7,12 @@ export class OpenAIProvider {
     }
     async chat(params) {
         const messages = [
-            { role: "system", content: params.system },
+            { role: "developer", content: params.system },
             ...params.messages.map((m) => this.toOpenAIMessage(m)),
         ];
         const response = await this.client.chat.completions.create({
-            model: params.model ?? "gpt-4o",
-            max_tokens: params.maxTokens ?? 8192,
+            model: params.model ?? "gpt-5.2",
+            max_completion_tokens: params.maxTokens ?? 8192,
             messages,
             ...(params.tools?.length
                 ? {
@@ -54,12 +54,12 @@ export class OpenAIProvider {
     }
     async *stream(params) {
         const messages = [
-            { role: "system", content: params.system },
+            { role: "developer", content: params.system },
             ...params.messages.map((m) => this.toOpenAIMessage(m)),
         ];
         const stream = await this.client.chat.completions.create({
-            model: params.model ?? "gpt-4o",
-            max_tokens: params.maxTokens ?? 8192,
+            model: params.model ?? "gpt-5.2",
+            max_completion_tokens: params.maxTokens ?? 8192,
             messages,
             stream: true,
             ...(params.tools?.length

package/dist/agents/runtime/types.js

@@ -7,9 +7,9 @@ export const MODEL_MAP = {
         advanced: "claude-opus-4-6",
     },
     openai: {
-        fast: "gpt-5.2-codex",
+        fast: "gpt-5.2",
         standard: "gpt-5.2",
-        advanced: "o3",
+        advanced: "gpt-5.2",
     },
     google: {
         fast: "gemini-2.5-flash",

package/dist/cli/analyze.js

@@ -5,7 +5,7 @@ import chalk from "chalk";
 import { resolveConfig } from "./config.js";
 import { recordUsage } from "./license-gate.js";
 import { staticResultToSpec, writeSpec, writeMetadata, loadSpec, loadMetadata } from "./yaml-io.js";
-import { getChangedFiles, mapFilesToComponents, shouldRunAgents, isGitAvailable } from "./incremental.js";
+import { getChangedFiles, mapFilesToComponents, shouldRunAgents, isGitAvailable, categorizeChanges, computeNeighbors, getCommitCount } from "./incremental.js";
 import { progressBar } from "./ui.js";
 export async function handleAnalyze(options) {
     const rootDir = options.dir ? path.resolve(options.dir) : process.cwd();
@@ -115,30 +115,63 @@ export async function handleAnalyze(options) {
     const priorSpec = loadSpec(rootDir);
     const priorMeta = loadMetadata(rootDir);
     if (priorSpec && !options.force && isGitAvailable(rootDir) && priorMeta?.lastCommit) {
-        const changedFiles = getChangedFiles(rootDir, priorMeta.lastCommit);
-        if (changedFiles.length === 0) {
-            console.log(chalk.green("No changes detected since last scan. Use --force to re-scan."));
+        // Staleness detection: force full scan after 20+ commits
+        const commitsSinceScan = getCommitCount(rootDir, priorMeta.lastCommit);
+        if (commitsSinceScan >= 20) {
+            console.log(chalk.yellow(`${commitsSinceScan} commits since last scan — forcing full re-scan for accuracy.`));
             console.log();
-            return;
         }
-        const { affected, unmapped } = mapFilesToComponents(changedFiles, priorSpec);
-        if (!shouldRunAgents(affected, unmapped)) {
-            console.log(chalk.green("Only config changes detected. No re-scan needed. Use --force to re-scan."));
+        else {
+            const changedFiles = getChangedFiles(rootDir, priorMeta.lastCommit);
+            if (changedFiles.length === 0) {
+                console.log(chalk.green("No changes detected since last scan. Use --force to re-scan."));
+                console.log();
+                return;
+            }
+            const { affected, unmapped } = mapFilesToComponents(changedFiles, priorSpec);
+            if (!shouldRunAgents(affected, unmapped)) {
+                console.log(chalk.green("Only config changes detected. No re-scan needed. Use --force to re-scan."));
+                console.log();
+                return;
+            }
+            const categories = categorizeChanges(changedFiles);
+            const neighborComponents = computeNeighbors(affected, priorSpec);
+            incrementalContext = {
+                existingSpec: priorSpec,
+                changedFiles,
+                affectedComponents: [...affected],
+                categories,
+                neighborComponents,
+                hasUnmappedFiles: unmapped.length > 0,
+            };
+            console.log(chalk.bold("Incremental scan:"));
+            console.log(chalk.gray(`  Changed files: ${changedFiles.length}`));
+            console.log(chalk.gray(`  Affected components: ${affected.size > 0 ? [...affected].join(", ") : "none (new files)"}`));
+            if (neighborComponents.length > 0) {
+                console.log(chalk.gray(`  Neighbor components: ${neighborComponents.join(", ")}`));
+            }
+            if (unmapped.length > 0) {
+                console.log(chalk.gray(`  Unmapped files: ${unmapped.length} (potential new components — all agents will run)`));
+            }
+            // Summarize categorized changes
+            const catSummary = [];
+            if (categories.entryPoints.length)
+                catSummary.push(`${categories.entryPoints.length} entry`);
+            if (categories.routeFiles.length)
+                catSummary.push(`${categories.routeFiles.length} route`);
+            if (categories.infraFiles.length)
+                catSummary.push(`${categories.infraFiles.length} infra`);
+            if (categories.configFiles.length)
+                catSummary.push(`${categories.configFiles.length} config`);
+            if (categories.eventFiles.length)
+                catSummary.push(`${categories.eventFiles.length} event`);
+            if (categories.sourceFiles.length)
+                catSummary.push(`${categories.sourceFiles.length} source`);
+            if (catSummary.length > 0) {
+                console.log(chalk.gray(`  Categories: ${catSummary.join(", ")}`));
+            }
             console.log();
-            return;
         }
-        incrementalContext = {
-            existingSpec: priorSpec,
-            changedFiles,
-            affectedComponents: [...affected],
-        };
-        console.log(chalk.bold("Incremental scan:"));
-        console.log(chalk.gray(`  Changed files: ${changedFiles.length}`));
-        console.log(chalk.gray(`  Affected components: ${affected.size > 0 ? [...affected].join(", ") : "none (new files)"}`));
-        if (unmapped.length > 0) {
-            console.log(chalk.gray(`  Unmapped files: ${unmapped.length} (potential new components)`));
-        }
-        console.log();
     }
     // 4. Run static context collection → LLM pipeline
     const progress = progressBar(7);
@@ -235,13 +268,21 @@ export async function handleAnalyze(options) {
     if (result.tokenUsage) {
         meta.tokenUsage = { input: result.tokenUsage.input, output: result.tokenUsage.output };
     }
+    if (incrementalContext) {
+        meta.incrementalMode = true;
+        meta.changedFiles = incrementalContext.changedFiles.length;
+        meta.affectedComponents = incrementalContext.affectedComponents;
+    }
+    if (result.skippedAgents && result.skippedAgents.length > 0) {
+        meta.skippedAgents = result.skippedAgents;
+    }
     writeAnalysis(rootDir, analysis);
     writeAnalysisStatus(rootDir, "success");
     // Dual-write: archbyte.yaml + metadata.json
     const existingSpec = loadSpec(rootDir);
     const spec = staticResultToSpec(result, rootDir, existingSpec?.rules);
     writeSpec(rootDir, spec);
-    writeScanMetadata(rootDir, duration, "pipeline", ctx.fileTree.totalFiles, result.tokenUsage);
+    writeScanMetadata(rootDir, duration, "pipeline", ctx.fileTree.totalFiles, result.tokenUsage, incrementalContext ? true : undefined, result.skippedAgents);
     progress.update(6, "Generating diagram...");
     await autoGenerate(rootDir, options);
     progress.done("Analysis complete");
@@ -283,7 +324,7 @@ function getGitCommit() {
         return undefined;
     }
 }
-function writeScanMetadata(rootDir, durationMs, mode, filesScanned, tokenUsage) {
+function writeScanMetadata(rootDir, durationMs, mode, filesScanned, tokenUsage, incrementalMode, skippedAgents) {
     const meta = {
         analyzedAt: new Date().toISOString(),
         durationMs,
@@ -294,6 +335,10 @@ function writeScanMetadata(rootDir, durationMs, mode, filesScanned, tokenUsage)
         meta.filesScanned = filesScanned;
     if (tokenUsage)
         meta.tokenUsage = tokenUsage;
+    if (incrementalMode)
+        meta.incrementalMode = true;
+    if (skippedAgents && skippedAgents.length > 0)
+        meta.skippedAgents = skippedAgents;
     writeMetadata(rootDir, meta);
 }
 async function autoGenerate(rootDir, options) {

package/dist/cli/auth.js

@@ -46,8 +46,8 @@ export async function handleLogin(provider) {
         console.log(chalk.green(`Logged in as ${chalk.bold(credentials.email)} (${credentials.tier} tier)`));
         console.log(chalk.gray(`Credentials saved to ${CREDENTIALS_PATH}`));
         console.log();
-        console.log(chalk.gray("Your credentials and API keys are stored locally on your machine."));
-        console.log(chalk.gray("ArchByte never transmits or stores your model provider keys."));
+        console.log(chalk.gray("Login credentials are stored in ~/.archbyte/ (global) — never inside your project."));
+        console.log(chalk.gray("Your API keys and credentials never leave this machine."));
     }
     catch (err) {
         console.error(chalk.red(`Login failed: ${err instanceof Error ? err.message : "Unknown error"}`));

package/dist/cli/incremental.d.ts

@@ -21,3 +21,24 @@ export declare function shouldRunAgents(affected: Set<string>, unmapped: string[
  * Check if git is available and this is a git repo.
  */
 export declare function isGitAvailable(rootDir: string): boolean;
+/**
+ * Categorize changed files by domain relevance for agent filtering.
+ */
+export interface CategorizedChanges {
+    entryPoints: string[];
+    routeFiles: string[];
+    configFiles: string[];
+    infraFiles: string[];
+    eventFiles: string[];
+    sourceFiles: string[];
+}
+export declare function categorizeChanges(changedFiles: string[]): CategorizedChanges;
+/**
+ * Find 1-layer neighbor components: components connected to affected components.
+ * Ensures cross-component connections aren't missed during incremental scans.
+ */
+export declare function computeNeighbors(affectedComponents: Set<string>, spec: ArchbyteSpec): string[];
+/**
+ * Count commits since a given commit hash. Used for staleness detection.
+ */
+export declare function getCommitCount(rootDir: string, sinceCommit: string): number;

package/dist/cli/incremental.js

@@ -9,7 +9,7 @@ export function getChangedFiles(rootDir, sinceCommit) {
     try {
         const files = [];
         if (sinceCommit) {
-            // Changed files since last scan commit
+            // Changed files since last scan commit (committed changes)
             const diff = execSync(`git diff --name-only ${sinceCommit}..HEAD`, {
                 cwd: rootDir,
                 encoding: "utf-8",
@@ -19,6 +19,30 @@ export function getChangedFiles(rootDir, sinceCommit) {
                 files.push(...diff.split("\n").filter(Boolean));
             }
         }
+        // Include unstaged modifications to tracked files
+        const modified = execSync("git diff --name-only", {
+            cwd: rootDir,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        if (modified) {
+            for (const f of modified.split("\n").filter(Boolean)) {
+                if (!files.includes(f))
+                    files.push(f);
+            }
+        }
+        // Include staged but uncommitted changes
+        const staged = execSync("git diff --name-only --cached", {
+            cwd: rootDir,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        if (staged) {
+            for (const f of staged.split("\n").filter(Boolean)) {
+                if (!files.includes(f))
+                    files.push(f);
+            }
+        }
         // Also include untracked files
         const untracked = execSync("git ls-files --others --exclude-standard", {
             cwd: rootDir,
@@ -100,6 +124,72 @@ export function isGitAvailable(rootDir) {
         return false;
     }
 }
+export function categorizeChanges(changedFiles) {
+    const categories = {
+        entryPoints: [],
+        routeFiles: [],
+        configFiles: [],
+        infraFiles: [],
+        eventFiles: [],
+        sourceFiles: [],
+    };
+    for (const file of changedFiles) {
+        const name = file.split("/").pop() ?? "";
+        const lower = file.toLowerCase();
+        if (isInfraFile(lower, name)) {
+            categories.infraFiles.push(file);
+        }
+        else if (isConfigFile(name)) {
+            categories.configFiles.push(file);
+        }
+        else if (isEntryPoint(name)) {
+            categories.entryPoints.push(file);
+        }
+        else if (isRouteFile(lower, name)) {
+            categories.routeFiles.push(file);
+        }
+        else if (isEventFile(lower, name)) {
+            categories.eventFiles.push(file);
+        }
+        else if (isSourceFile(name)) {
+            categories.sourceFiles.push(file);
+        }
+        // else: non-code file (docs, images, etc.) — ignored
+    }
+    return categories;
+}
+/**
+ * Find 1-layer neighbor components: components connected to affected components.
+ * Ensures cross-component connections aren't missed during incremental scans.
+ */
+export function computeNeighbors(affectedComponents, spec) {
+    const neighbors = new Set();
+    for (const conn of spec.connections) {
+        if (affectedComponents.has(conn.from) && !affectedComponents.has(conn.to)) {
+            neighbors.add(conn.to);
+        }
+        if (affectedComponents.has(conn.to) && !affectedComponents.has(conn.from)) {
+            neighbors.add(conn.from);
+        }
+    }
+    return [...neighbors];
+}
+/**
+ * Count commits since a given commit hash. Used for staleness detection.
+ */
+export function getCommitCount(rootDir, sinceCommit) {
+    try {
+        const output = execSync(`git rev-list --count ${sinceCommit}..HEAD`, {
+            cwd: rootDir,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        return parseInt(output, 10) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
 // Helpers
 function normalizePath(p) {
     // Remove trailing slashes, normalize
@@ -109,3 +199,29 @@ function isConfigOnly(filePath) {
     const name = filePath.split("/").pop() ?? "";
     return /^(\.gitignore|\.eslintrc|\.prettierrc|tsconfig|package\.json|package-lock|yarn\.lock|pnpm-lock|archbyte\.yaml|README|LICENSE|CHANGELOG|\.env)/i.test(name);
 }
+function isInfraFile(lower, name) {
+    return /dockerfile|docker-compose|compose\.ya?ml|\.dockerignore/i.test(name) ||
+        lower.includes("k8s/") || lower.includes("kubernetes/") ||
+        lower.includes("terraform/") || lower.includes("helm/") ||
+        /\.(tf|hcl)$/.test(name);
+}
+function isConfigFile(name) {
+    return /^(package\.json|tsconfig|\.env|\.eslintrc|\.prettierrc|pyproject\.toml|Cargo\.toml|go\.mod|archbyte\.yaml)/i.test(name);
+}
+function isEntryPoint(name) {
+    return /^(index|main|app|server|entry)\.(ts|js|tsx|jsx|py|go|rs)$/i.test(name);
+}
+function isRouteFile(lower, name) {
+    return lower.includes("route") || lower.includes("router") ||
+        lower.includes("controller") || lower.includes("handler") ||
+        /\.(routes|controller|handler)\.(ts|js)$/i.test(name);
+}
+function isEventFile(lower, name) {
+    return lower.includes("event") || lower.includes("listener") ||
+        lower.includes("subscriber") || lower.includes("consumer") ||
+        lower.includes("producer") || lower.includes("queue") ||
+        /\.(events?|listener|subscriber|consumer|producer)\.(ts|js)$/i.test(name);
+}
+function isSourceFile(name) {
+    return /\.(ts|tsx|js|jsx|py|go|rs|java|kt|rb|cs|php|swift|dart)$/i.test(name);
+}

package/dist/cli/serve.js

@@ -2,12 +2,51 @@ import * as path from "path";
 import * as fs from "fs";
 import chalk from "chalk";
 import { DEFAULT_PORT } from "./constants.js";
+import { select } from "./ui.js";
+function askPort(prompt) {
+    return new Promise((resolve) => {
+        process.stdout.write(prompt);
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        let input = "";
+        const onData = (data) => {
+            for (const ch of data) {
+                if (ch === "\n" || ch === "\r" || ch === "\u0004") {
+                    stdin.setRawMode(wasRaw ?? false);
+                    stdin.pause();
+                    stdin.removeListener("data", onData);
+                    process.stdout.write("\n");
+                    resolve(input);
+                    return;
+                }
+                else if (ch === "\u0003") {
+                    process.stdout.write("\n");
+                    process.exit(0);
+                }
+                else if (ch === "\u007F" || ch === "\b") {
+                    if (input.length > 0) {
+                        input = input.slice(0, -1);
+                        process.stdout.write("\b \b");
+                    }
+                }
+                else if (ch >= "0" && ch <= "9") {
+                    input += ch;
+                    process.stdout.write(ch);
+                }
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
 /**
  * Start the ArchByte UI server
  */
 export async function handleServe(options) {
     const rootDir = process.cwd();
-    const port = options.port || DEFAULT_PORT;
+    let port = options.port || DEFAULT_PORT;
     const diagramPath = options.diagram
         ? path.resolve(rootDir, options.diagram)
         : path.join(rootDir, ".archbyte", "architecture.json");
@@ -25,7 +64,6 @@ export async function handleServe(options) {
     }
     console.log(chalk.cyan(`🏗️  ArchByte - See what agents build. As they build it.`));
     console.log(chalk.gray(`Diagram: ${path.relative(rootDir, diagramPath)}`));
-    console.log(chalk.gray(`Port: ${port}`));
     console.log();
     // Check if diagram exists
     if (!fs.existsSync(diagramPath)) {
@@ -34,26 +72,66 @@ export async function handleServe(options) {
         console.log();
     }
     const { startServer } = await import("../server/src/index.js");
-    const maxRetries = 10;
-    for (let attempt = 0; attempt < maxRetries; attempt++) {
-        const tryPort = port + attempt;
+    // Try to start, handle port conflicts interactively
+    while (true) {
         try {
-            if (attempt > 0) {
-                console.log(chalk.gray(`Port ${tryPort - 1} in use, trying ${tryPort}...`));
-            }
-            console.log(chalk.green(`UI: http://localhost:${tryPort}`));
+            console.log(chalk.green(`UI: http://localhost:${port}`));
             console.log();
             await startServer({
                 name: projectName,
                 diagramPath,
                 workspaceRoot: rootDir,
-                port: tryPort,
+                port,
             });
             return;
         }
         catch (error) {
             if (error instanceof Error && error.code === "EADDRINUSE") {
-                continue;
+                console.log(chalk.yellow(`  Port ${port} is already in use.`));
+                console.log();
+                if (!process.stdin.isTTY) {
+                    // Non-interactive — just try next port
+                    port++;
+                    continue;
+                }
+                const nextPort = port + 1;
+                const choice = await select("  What would you like to do?", [
+                    `Use next available port (${nextPort})`,
+                    "Enter a custom port",
+                    "Kill the process on this port and retry",
+                    "Exit",
+                ]);
+                if (choice === 0) {
+                    port = nextPort;
+                    continue;
+                }
+                else if (choice === 1) {
+                    const input = await askPort(chalk.bold("  Port: "));
+                    const parsed = parseInt(input, 10);
+                    if (!parsed || parsed < 1 || parsed > 65535) {
+                        console.log(chalk.red("  Invalid port number."));
+                        continue;
+                    }
+                    port = parsed;
+                    continue;
+                }
+                else if (choice === 2) {
+                    try {
+                        const { execSync } = await import("child_process");
+                        execSync(`lsof -ti:${port} | xargs kill -9`, { stdio: "ignore" });
+                        console.log(chalk.green(`  Killed process on port ${port}.`));
+                        // Small delay for OS to release the port
+                        await new Promise((r) => setTimeout(r, 500));
+                        continue;
+                    }
+                    catch {
+                        console.log(chalk.red(`  Could not kill process on port ${port}. Try manually: lsof -ti:${port} | xargs kill -9`));
+                        continue;
+                    }
+                }
+                else {
+                    process.exit(0);
+                }
             }
             if (error instanceof Error) {
                 console.error(chalk.red(`Error: ${error.message}`));
@@ -61,6 +139,4 @@ export async function handleServe(options) {
             process.exit(1);
         }
     }
-    console.error(chalk.red(`All ports ${port}-${port + maxRetries - 1} are in use.`));
-    process.exit(1);
 }

package/dist/cli/setup.js

@@ -16,7 +16,7 @@ const PROVIDERS = [
 ];
 const PROVIDER_MODELS = {
     anthropic: [
-        { id: "", label: "Default (recommended)", hint: "Haiku for fast agents, Sonnet for connections" },
+        { id: "", label: "Default (recommended)", hint: "Opus for all agents" },
         { id: "claude-haiku-4-5-20251001", label: "Claude Haiku 4.5", hint: "Fastest, cheapest" },
         { id: "claude-sonnet-4-5-20250929", label: "Claude Sonnet 4.5", hint: "Balanced, great quality" },
         { id: "claude-opus-4-6", label: "Claude Opus 4.6", hint: "Most capable" },
@@ -292,8 +292,16 @@ export async function handleSetup() {
             console.log(chalk.green(`  ✓ Model: ${chosen.label}`));
         }
         else {
-            delete profiles[provider].model;
-            console.log(chalk.green(`  ✓ Model: Default (auto per agent tier)`));
+            // Save the actual default model so config is explicit
+            const defaultModels = {
+                anthropic: "claude-opus-4-6",
+                openai: "gpt-5.2",
+                google: "gemini-2.5-pro",
+                ollama: "qwen2.5-coder",
+            };
+            const defaultModel = defaultModels[provider] ?? resolveModel(provider, "standard");
+            profiles[provider].model = defaultModel;
+            console.log(chalk.green(`  ✓ Model: ${defaultModel} (default)`));
         }
     }
     config.profiles = profiles;
@@ -329,13 +337,11 @@ export async function handleSetup() {
     delete config.ollamaBaseUrl;
     // Save config
     saveConfig(config);
-    console.log(chalk.gray(`\n  Config saved to ${CONFIG_PATH}`));
-    console.log(chalk.gray("  Your API key is stored locally on this machine and never sent to ArchByte."));
-    console.log(chalk.gray("  All model calls go directly from your machine to your provider."));
     // Generate archbyte.yaml in .archbyte/ if it doesn't exist
     const projectDir = process.cwd();
     const archbyteDir = path.join(projectDir, ".archbyte");
     const yamlPath = path.join(archbyteDir, "archbyte.yaml");
+    let yamlCreated = false;
     if (!fs.existsSync(yamlPath)) {
         if (!fs.existsSync(archbyteDir)) {
             fs.mkdirSync(archbyteDir, { recursive: true });
@@ -355,21 +361,39 @@ export async function handleSetup() {
         let template = fs.readFileSync(templatePath, "utf-8");
         template = template.replace("name: my-project", `name: ${projectName}`);
         fs.writeFileSync(yamlPath, template, "utf-8");
-        console.log(chalk.green(`  Created .archbyte/archbyte.yaml`));
-    }
-    else {
-        console.log(chalk.gray(`  .archbyte/archbyte.yaml already exists`));
+        yamlCreated = true;
     }
     // Generate README.md in .archbyte/
     writeArchbyteReadme(archbyteDir);
+    // ─── Summary ───
+    const dim = chalk.gray;
+    const sep = dim("  ───");
+    console.log();
+    console.log(chalk.bold.green("  ✓ Setup complete"));
+    console.log();
+    console.log(sep);
+    console.log();
+    console.log(dim("  ~/.archbyte/") + "   API keys, login, config   " + dim("(global)"));
+    console.log(dim("  .archbyte/") + "     Analysis, diagrams        " + dim("(per project)"));
+    console.log();
+    console.log(dim("  Your keys never leave this machine."));
+    console.log(dim("  All model calls go directly to your provider."));
     console.log();
-    console.log(chalk.green("  Setup complete!"));
+    console.log(sep);
     console.log();
-    console.log(chalk.bold("  Next: ") + chalk.cyan("archbyte run") + chalk.bold(" to analyze your codebase."));
-    console.log(chalk.gray("        Run from your project root, or use ") + chalk.cyan("archbyte run -d /path/to/project"));
+    if (yamlCreated) {
+        console.log(chalk.green("  + ") + "Created " + chalk.cyan(".archbyte/archbyte.yaml"));
+    }
+    else {
+        console.log(dim("  .archbyte/archbyte.yaml already exists"));
+    }
+    console.log();
+    console.log(sep);
+    console.log();
+    console.log("  " + chalk.bold("Next"));
+    console.log("  " + chalk.cyan("archbyte run") + "            Analyze your codebase");
     if (hasClaude || hasCodex) {
-        console.log();
-        console.log(chalk.bold("  MCP:  ") + chalk.cyan("archbyte mcp install") + chalk.bold(" to use ArchByte from your AI tool."));
+        console.log("  " + chalk.cyan("archbyte mcp install") + "    Use from your AI tool");
     }
     console.log();
 }

package/dist/cli/yaml-io.d.ts

@@ -71,6 +71,8 @@ export interface ScanMetadata {
     };
     validation?: unknown;
     gaps?: unknown;
+    incrementalMode?: boolean;
+    skippedAgents?: string[];
 }
 export declare function loadSpec(rootDir: string): ArchbyteSpec | null;
 export declare function writeSpec(rootDir: string, spec: ArchbyteSpec): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archbyte",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "ArchByte - See what agents build. As they build it.",
   "type": "module",
   "bin": {