@eyeauras/insight-cli 0.3.0 → 0.3.2

package/dist/src/initial-model.js

@@ -2,6 +2,7 @@ import { mkdir, realpath, readFile, open, link, unlink } from 'node:fs/promises'
 import { join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { stable, object, fail } from './model.js';
+import { initialProgress, progressPhase, readInitialProgress } from './initial-progress.js';
 export const initialRoot = (workspace, target) => join(workspace.directory, 'ghidra-native', 'initial', target);
 export async function initialIntent(workspace, target) {
     try {
@@ -15,6 +16,24 @@ export async function initialIntent(workspace, target) {
 }
 /** Immutable input/authority binding; private attempts and conditional first creation share it. */
 export async function initializeModel(workspace, target, binding, server, fingerprint) {
+    try {
+        return await initialize(workspace, target, binding, server, fingerprint);
+    }
+    catch (error) {
+        try {
+            const progress = await readInitialProgress(workspace.directory, target.id);
+            // A busy or disconnected caller must not overwrite another live native worker's observation.
+            if (progress && progress.state !== 'complete' && (progress.pid === process.pid || progress.workerAlive === false)) {
+                const code = String(error.code ?? '');
+                const state = code === 'tool.timeout' ? 'timed_out' : code === 'tool.cancelled' ? 'cancelled' : progress.state === 'failed' || progress.state === 'cancelled' ? progress.state : 'unknown';
+                await initialProgress(initialRoot(workspace, target.id), target.id, progress.phase, state);
+            }
+        }
+        catch { /* Preserve the authoritative operation failure when observation storage also fails. */ }
+        throw error;
+    }
+}
+async function initialize(workspace, target, binding, server, fingerprint) {
     const root = initialRoot(workspace, target.id);
     await mkdir(root, { recursive: true, mode: 0o700 });
     if (await realpath(root) !== resolve(root))
@@ -67,20 +86,22 @@ export async function initializeModel(workspace, target, binding, server, finger
     const receipt = object(JSON.parse(await readFile(join(root, 'import.json'), 'utf8'))), name = receipt.snapshot;
     if (typeof name !== 'string' || !/^attempt-[a-f0-9-]{36}\.gzf$/.test(name))
         fail('binding', 'Initial model snapshot receipt is malformed.');
-    const snapshot = await workspace.captureSnapshot(join(root, name));
+    const snapshot = await progressPhase(root, target.id, 'snapshot-verification', () => workspace.captureSnapshot(join(root, name)));
     if (snapshot.sha256 !== receipt.snapshotSha256)
         fail('binding', 'Initial saved snapshot changed before publication.');
-    let result = await server.initialPublication(binding, root, 'stage');
+    const publication = (operation) => progressPhase(root, target.id, 'publication-' + operation, () => server.initialPublication(binding, root, operation));
+    let result = await publication('stage');
     if (result.state === 'staged') {
-        const proof = await server.initialPublication(binding, root, 'verify-stage');
+        const proof = await publication('verify-stage');
         if (proof.state !== 'stage_verified' || proof.version !== 1 || proof.snapshotBuffersVerified !== true)
             fail('unknown', 'Independent initial staging readback did not establish the complete snapshot.');
-        result = await server.initialPublication(binding, root, 'promote');
+        result = await publication('promote');
     }
     if (result.state !== 'published' || result.version !== 1 || result.snapshotBuffersVerified !== true)
         fail('unknown', 'Initial publication requires reconciliation against its saved snapshot.');
-    const verified = await server.initialPublication(binding, root, 'verify');
+    const verified = await publication('verify');
     if (verified.state !== 'verified' || verified.version !== 1 || verified.snapshotBuffersVerified !== true)
         fail('unknown', 'Independent initial-model readback did not establish the complete saved buffers.');
     workspace.establishModel(target.id, 1, snapshot);
+    await initialProgress(root, target.id, 'complete', 'complete');
 }

package/dist/src/initial-progress.d.ts

@@ -0,0 +1,4 @@
+/** Observation only. Completion receipts and the workspace remain the outcome authority. */
+export declare function readInitialProgress(directory: string, target: string): Promise<any>;
+export declare function initialProgress(root: string, target: string, phase: string, state?: string): Promise<void>;
+export declare function progressPhase<T>(root: string, target: string, phase: string, action: () => Promise<T>): Promise<T>;

package/dist/src/initial-progress.js

@@ -0,0 +1,64 @@
+import { readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { atomicWrite } from './tool-runtime/store.js';
+/** Observation only. Completion receipts and the workspace remain the outcome authority. */
+export async function readInitialProgress(directory, target) {
+    try {
+        const value = JSON.parse(await readFile(join(directory, 'ghidra-native', 'initial', target, 'progress.json'), 'utf8'));
+        if (value.schema !== 1 || value.target !== target)
+            throw Error('Invalid initial progress binding');
+        const ageMs = Math.max(0, Date.now() - Date.parse(value.updatedAt));
+        let workerAlive;
+        if (Number.isSafeInteger(value.pid) && value.pid > 0)
+            try {
+                process.kill(value.pid, 0);
+                workerAlive = true;
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    workerAlive = false;
+            }
+        return { ...value, operation: 'initial-model', ageMs, elapsedMs: Math.max(0, (value.state === 'running' ? Date.now() : Date.parse(value.updatedAt)) - Date.parse(value.startedAt)),
+            ...(workerAlive === undefined ? {} : { workerAlive }),
+            observation: value.state === 'running' && (workerAlive === false || ageMs > 15000) ? 'stale' : 'current' };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function initialProgress(root, target, phase, state = 'running') {
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    let startedAt = new Date().toISOString();
+    try {
+        const previous = JSON.parse(await readFile(join(root, 'progress.json'), 'utf8'));
+        if (previous.target === target)
+            startedAt = previous.startedAt;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await atomicWrite(join(root, 'progress.json'), { schema: 1, target, phase, state, pid: process.pid, startedAt, updatedAt: new Date().toISOString(), indeterminate: true });
+}
+export async function progressPhase(root, target, phase, action) {
+    await initialProgress(root, target, phase);
+    let pending = Promise.resolve(), failure;
+    const timer = setInterval(() => { pending = pending.then(() => initialProgress(root, target, phase)).catch(error => { failure = error; }); }, 2000);
+    timer.unref();
+    let actionFailed = false;
+    try {
+        return await action();
+    }
+    catch (error) {
+        actionFailed = true;
+        throw error;
+    }
+    finally {
+        clearInterval(timer);
+        await pending;
+        if (failure && !actionFailed)
+            throw failure;
+    }
+}

package/dist/src/native-inputs.js

@@ -1,4 +1,5 @@
 import { runTool } from './tool-runtime/run.js';
+import { javaClasspathArguments } from './tool-runtime/java-arguments.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { readFile, writeFile, readdir, mkdir, open, rename, rm, realpath, stat } from 'node:fs/promises';
 import { basename, delimiter, dirname, isAbsolute, join, relative, sep } from 'node:path';
@@ -158,7 +159,7 @@ export async function nativeHelpers(directory, inputs, c) {
         if (c)
             await runTool(c, { tool: 'ghidra', role: 'compile-helpers', installation: inputs.fingerprint, executable, arguments: args, timeoutMs: 60000, maxOutputBytes: 262144 });
         else
-            await run(executable, args, { timeout: 60000, maxBuffer: 262144 });
+            await run(executable, await javaClasspathArguments(temporary, 'ghidra', executable, args), { timeout: 60000, maxBuffer: 262144 });
         const complete = await open(join(temporary, 'complete'), 'wx', 0o600);
         try {
             await complete.writeFile(key);

package/dist/src/server.js

@@ -203,6 +203,16 @@ export class GhidraServer {
     }
     async initialImport(root) {
         const timeoutMilliseconds = ghidraBudget(this.c.profile.values, 'import');
+        const report = async () => {
+            try {
+                const p = object(JSON.parse(await readFile(join(root, 'progress.json'), 'utf8')));
+                const elapsed = Math.round((Date.now() - Date.parse(String(p.startedAt))) / 1000);
+                this.c.progress(`Ghidra ${String(p.phase)}: ${elapsed}s${typeof p.total === 'number' ? `; task ${String(p.completed)}/${p.total}` : ''}${p.message ? `; ${String(p.message).replace(/[\r\n\x00-\x1f]/g, ' ')}` : ''}`);
+            }
+            catch { /* Progress observation never changes the native operation's outcome. */ }
+        };
+        const timer = setInterval(() => { void report(); }, 5000);
+        timer.unref();
         try {
             return await this.run('initial-import', 'InsightInitialImport', [root], {}, undefined, [0], timeoutMilliseconds);
         }
@@ -211,8 +221,12 @@ export class GhidraServer {
                 throw new CliError(error.message + ' Initial import remains unproved. Increase profile initialImportSeconds and continue the original scope; incomplete private analysis restarts from the retained input.', { code: error.code, result: { phase: 'initial-import', timeoutMilliseconds, budgetSetting: 'initialImportSeconds', outcome: 'unknown', diagnostics: error.result } });
             throw error;
         }
+        finally {
+            clearInterval(timer);
+        }
     }
     async initialPublication(binding, root, operation = 'stage') {
+        this.c.progress('Ghidra initial publication: ' + operation);
         return this.run('initial-publication', 'db.InsightInitialPublication', [root, operation], await this.credentials(binding, operation.startsWith('verify') ? 'reader' : 'publisher'));
     }
     async publish(binding, path, snapshot, expected, request, journal, sourceSha) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eyeauras/insight-cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "Agent-facing durable sessions and isolated Ghidra research contexts",
   "main": "./dist/src/index.js",

package/references/native/InsightImportProgress.java

@@ -0,0 +1,42 @@
+import com.google.gson.*;
+import ghidra.util.task.TaskMonitorAdapter;
+import insight.InsightInitialJournal;
+import java.nio.file.*;
+import java.time.Instant;
+import java.util.*;
+
+/** A bounded observation channel, never a completion receipt or an overall percentage. */
+class InsightImportProgress extends TaskMonitorAdapter implements AutoCloseable {
+    private final Path root;
+    private final String target,started=Instant.now().toString();
+    private final Timer heartbeat=new Timer("insight-import-progress",true);
+    private String phase="starting",state="running";
+    private String message="";
+    private long completed,total;
+    private boolean indeterminate=true;
+    private volatile Throwable writeFailure;
+    InsightImportProgress(Path root,String target)throws Exception{
+        super(true);this.root=root;this.target=target;emit();
+        heartbeat.scheduleAtFixedRate(new TimerTask(){public void run(){try{emit();}catch(Throwable failure){writeFailure=failure;}}},2000,2000);
+    }
+    synchronized void phase(String value)throws Exception{phase=value;setMessage("");initialize(0);setIndeterminate(true);emit();}
+    public synchronized void setMessage(String value){message=Objects.toString(value,"");}
+    public synchronized String getMessage(){return message;}
+    public synchronized void initialize(long maximum){completed=0;total=maximum;indeterminate=maximum<=0;}
+    public synchronized void setProgress(long value){completed=value;}
+    public synchronized void incrementProgress(long value){completed+=value;}
+    public synchronized long getProgress(){return completed;}
+    public synchronized void setMaximum(long value){total=value;}
+    public synchronized long getMaximum(){return total;}
+    public synchronized void setIndeterminate(boolean value){indeterminate=value;}
+    public synchronized boolean isIndeterminate(){return indeterminate;}
+    synchronized void state(String value)throws Exception{state=value;emit();}
+    private synchronized void emit()throws Exception{
+        JsonObject p=new JsonObject();p.addProperty("schema",1);p.addProperty("target",target);p.addProperty("phase",phase);p.addProperty("state",state);
+        p.addProperty("pid",ProcessHandle.current().pid());p.addProperty("startedAt",started);p.addProperty("updatedAt",Instant.now().toString());
+        p.addProperty("indeterminate",isIndeterminate());String message=Objects.toString(getMessage(),"");p.addProperty("message",message.substring(0,Math.min(message.length(),1024)));
+        if(!isIndeterminate()&&getMaximum()>0){p.addProperty("completed",getProgress());p.addProperty("total",getMaximum());}
+        InsightInitialJournal.write(root.resolve("progress.json"),p);
+    }
+    public synchronized void close()throws Exception{heartbeat.cancel();if(state.equals("running"))state=isCancelled()?"cancelled":"failed";emit();if(writeFailure!=null)throw new java.io.IOException("Progress persistence failed",writeFailure);}
+}

package/references/native/InsightInitialImport.java

@@ -23,6 +23,8 @@ class InsightInitialImport {
                 JsonObject s=new JsonObject();s.addProperty("intentHash",InsightInitialJournal.hash(root.resolve("intent.json")));
                 s.addProperty("phase","importing");s.addProperty("pid",ProcessHandle.current().pid());s.addProperty("snapshot","attempt-"+UUID.randomUUID()+".gzf");
                 Path attempt=root.resolve(InsightInitialJournal.text(s,"snapshot")+".json");InsightInitialJournal.write(attempt,s);InsightInitialJournal.write(journal,s);
+                try(var progress=new InsightImportProgress(root,InsightInitialJournal.text(p,"target"))){
+                progress.phase("runtime-initialization");
                 Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
                 JsonObject settings=p.getAsJsonObject("settings"),request=new JsonObject();
                 request.addProperty("input",input.toString());request.addProperty("output",root.resolve(InsightInitialJournal.text(s,"snapshot")).toString());
@@ -31,10 +33,14 @@ class InsightInitialImport {
                 if(settings.has("compilerSpec"))request.add("compiler_spec",settings.get("compilerSpec"));
                 if(settings.has("imageBase"))request.add("image_base",settings.get("imageBase"));
                 if(settings.has("loaderOptions"))request.add("options",settings.get("loaderOptions"));
-                JsonObject metadata=new Gson().toJsonTree(InsightSdkFiles.importProgram(request)).getAsJsonObject();
+                JsonObject metadata;
+                try{metadata=new Gson().toJsonTree(InsightSdkFiles.importProgram(request,progress)).getAsJsonObject();}
+                catch(Throwable failure){progress.state(progress.isCancelled()?"cancelled":"failed");throw failure;}
+                progress.phase("snapshot-verification");
                 Path file=root.resolve(InsightInitialJournal.text(s,"snapshot"));InsightInitialJournal.sync(file);
                 s.add("metadata",metadata);s.addProperty("snapshotSha256",InsightInitialJournal.hash(file));s.addProperty("phase","prepared");InsightInitialJournal.write(attempt,s);InsightInitialJournal.write(journal,s);
-                InsightInitialJournal.prepared(root);out.println("{\"state\":\"prepared\"}");
+                InsightInitialJournal.prepared(root);progress.state("prepared");out.println("{\"state\":\"prepared\"}");
+                }
             }
             System.exit(0);
         }catch(Throwable failure){failure.printStackTrace(System.err);out.println("{\"state\":\"failed\"}");System.exit(1);}

package/references/native/InsightSdkFiles.java

@@ -54,14 +54,17 @@ class InsightSdkFiles {
             return Map.of("supported",rows,"all_loader_names",LoaderService.getAllLoaderNames());
         }
     }
-    static Object importProgram(JsonObject p) throws Exception {
+    static void phase(TaskMonitor monitor,String phase)throws Exception{if(monitor instanceof InsightImportProgress progress)progress.phase(phase);}
+    static Object importProgram(JsonObject p) throws Exception {return importProgram(p,TaskMonitor.DUMMY);}
+    static Object importProgram(JsonObject p,TaskMonitor monitor) throws Exception {
+        phase(monitor,"import");
         String selected=text(p,"loader");Object consumer=new Object();Loader loader=null;
         if(selected.isEmpty()){
             Language language=text(p,"language").isEmpty()?null:DefaultLanguageService.getLanguageService().getLanguage(new LanguageID(text(p,"language")));
             CompilerSpec compiler=language==null?null:text(p,"compiler_spec").isEmpty()?language.getDefaultCompilerSpec():language.getCompilerSpecByID(new CompilerSpecID(text(p,"compiler_spec")));
-            var loaded=language==null?AutoImporter.importByUsingBestGuess(Path.of(text(p,"input")).toFile(),null,"/",consumer,new MessageLog(),TaskMonitor.DUMMY):
-                AutoImporter.importByLookingForLcs(Path.of(text(p,"input")).toFile(),null,"/",language,compiler,consumer,new MessageLog(),TaskMonitor.DUMMY);
-            try{if(loaded==null||loaded.size()!=1)throw new IllegalArgumentException("Expected one imported program");return saveImport(loaded.getPrimaryDomainObject(),p,"automatic");}
+            var loaded=language==null?AutoImporter.importByUsingBestGuess(Path.of(text(p,"input")).toFile(),null,"/",consumer,new MessageLog(),monitor):
+                AutoImporter.importByLookingForLcs(Path.of(text(p,"input")).toFile(),null,"/",language,compiler,consumer,new MessageLog(),monitor);
+            try{if(loaded==null||loaded.size()!=1)throw new IllegalArgumentException("Expected one imported program");return saveImport(loaded.getPrimaryDomainObject(),p,"automatic",monitor);}
             finally{if(loaded!=null)loaded.release(consumer);}
         }
         for(Loader candidate:ClassSearcher.getInstances(Loader.class))if(candidate.getClass().getName().equals(selected)||candidate.getClass().getSimpleName().equals(selected)||candidate.getName().equals(selected)){
@@ -77,24 +80,24 @@ class InsightSdkFiles {
             Language effectiveLanguage=language;if(effectiveLanguage==null&&selectedSpec.getLanguageCompilerSpec()!=null)effectiveLanguage=DefaultLanguageService.getLanguageService().getLanguage(selectedSpec.getLanguageCompilerSpec().languageID);
             var options=configured(loader.getDefaultOptions(provider,selectedSpec,null,false,false),optionValues(p),effectiveLanguage==null?null:effectiveLanguage.getAddressFactory());
             String error=loader.validateOptions(provider,selectedSpec,options,null);if(error!=null)throw new IllegalArgumentException("Native loader rejected options: "+error);
-            var settings=new Loader.ImporterSettings(provider,"OwnedInput",null,"/",false,selectedSpec,options,consumer,new MessageLog(),TaskMonitor.DUMMY);
+            var settings=new Loader.ImporterSettings(provider,"OwnedInput",null,"/",false,selectedSpec,options,consumer,new MessageLog(),monitor);
             var result=loader.load(settings);
             if(result==null)throw new IllegalStateException("Native loader did not return a program");
             try {
                 if(result.size()!=1||!(result.getPrimaryDomainObject() instanceof Program))throw new IllegalArgumentException("Loader must produce one program per explicit target");
-                return saveImport((Program)result.getPrimaryDomainObject(),p,loader.getClass().getName());
+                return saveImport((Program)result.getPrimaryDomainObject(),p,loader.getClass().getName(),monitor);
             } finally {result.release(consumer);}
         }
     }
-    static Object saveImport(Program program,JsonObject p,String loader)throws Exception{
+    static Object saveImport(Program program,JsonObject p,String loader,TaskMonitor monitor)throws Exception{
         boolean analyze=p.has("auto_analyze")&&p.get("auto_analyze").getAsBoolean();
-        if(analyze){ghidra.app.script.GhidraScriptUtil.acquireBundleHostReference();int tx=program.startTransaction("Initial analysis");boolean success=false;
-            try{AutoAnalysisManager analysis=AutoAnalysisManager.getAnalysisManager(program);analysis.initializeOptions();analysis.reAnalyzeAll(null);analysis.startAnalysis(TaskMonitor.DUMMY);success=true;}
+        if(analyze){phase(monitor,"analysis");ghidra.app.script.GhidraScriptUtil.acquireBundleHostReference();int tx=program.startTransaction("Initial analysis");boolean success=false;
+            try{AutoAnalysisManager analysis=AutoAnalysisManager.getAnalysisManager(program);analysis.initializeOptions();analysis.reAnalyzeAll(null);analysis.startAnalysis(monitor);monitor.checkCancelled();success=true;}
             finally{program.endTransaction(tx,success);ghidra.app.script.GhidraScriptUtil.releaseBundleHostReference();}}
         if(p.has("image_base")){int tx=program.startTransaction("Initial image base");boolean success=false;
             try{program.setImageBase(program.getAddressFactory().getDefaultAddressSpace().getAddress(new BigInteger(text(p,"image_base"),16).longValue()),true);success=true;}
             finally{program.endTransaction(tx,success);}}
-        program.saveToPackedFile(Path.of(text(p,"output")).toFile(),TaskMonitor.DUMMY);
+        phase(monitor,"save");program.saveToPackedFile(Path.of(text(p,"output")).toFile(),monitor);monitor.checkCancelled();
         return Map.of("state","imported","loader",loader,"language",program.getLanguageID().toString(),"base_address",program.getImageBase().toString(),
             "compiler",program.getCompilerSpec().getCompilerSpecID().toString(),"sha256",program.getExecutableSHA256(),"auto_analyzed",analyze);
     }

package/references/setup.md

@@ -69,3 +69,30 @@ After an import timeout, wait for the original worker to end, raise its budget a
 the original scope. Incomplete private analysis restarts; a completed receipt is reused.
 A save timeout reports `phase: save`, the effective budget and `saveSeconds`. Inspect
 `sessions status`; a native log or broken response stream cannot prove a saved snapshot.
+
+## Initial import and progress
+
+New targets import **without automatic analysis**. Reuse existing selectors/projects before
+opening another copy; `ghidra open --session <session> --target <target>` preserves its bound
+load settings, including older analysis choices. `--no-analysis` makes the fast choice explicit;
+`--analysis` opts into a full analysis only during the first import of a new target.
+After a fast import, use scoped `ghidra analysis run` to process pending analysis, or
+`ghidra analysis reanalyze` to deliberately queue full reanalysis. These are saved private
+mutations; merge deliberately. For a narrow question prefer bounded function disassembly,
+function creation and decompilation first; inspect help for the exact operation.
+
+For long first opens, `ghidra progress --session <session> --target <target> --json`
+reads retained progress without starting Java or repeating the operation. It reports the
+current stage, elapsed time, heartbeat age and native task message/counters when available;
+those counters belong to the current task, not the whole import. Human output also reports
+progress through Factory; `--json` keeps one final JSON result on stdout and stays quiet.
+If the execution host yields, keep its same running execution and inspect progress every
+5-10 seconds when useful; relay stage changes or meaningful stalls, and do other independent
+work. Do not silently extend waits to minutes or start a second import. Until selectors are
+returned, use the existing `sessions list/status` and `tools processes` inventory to locate the
+reserved scope. A stale heartbeat, dead worker or unknown result is not completion: inspect
+`sessions status` and recovery before continuing. Pre-upgrade workers have no progress record;
+null progress means unavailable, never success. Progress is observational, not a completion receipt. This command tracks first open only;
+its old complete record does not describe later `analysis run`/`reanalyze` operations.
+`operation: initial-model` completes after verified shared-model publication; the private
+session context can still be opening. Inspect `sessions status` for context readiness.

package/references/storage.md

@@ -1,10 +1,19 @@
 # Analysis storage and migration
 
 `storage show --json` reports effective profile storage, availability, active file/byte usage,
-exact included trees and retained migration. The default is Factory profile AppData. No
-checkout, environment or automatic disk fallback changes it. The non-secret setting is
-`analysisDirectory` in Factory's profile (`profile show` also displays it). Use storage commands
-to change it safely.
+exact included trees, retained migration and installation default base. Before selecting a
+base, storage starts in Factory profile AppData. `configure` and `migrate` select that base
+for subsequent new/empty profiles as well as moving the current profile. Add `--profile-only`
+to keep the installation default unchanged. The effective root appends `insight-cli/<profile>`.
+Initialized profiles keep their existing locations when the default changes; profiles with
+ordinary AppData analysis trees stay there until explicitly migrated.
+
+The per-profile non-secret `analysisDirectory` setting remains in Factory's profile. The
+installation default is bound storage-control metadata beside Factory's profile store, paired
+with ownership metadata on the chosen base. It is not an environment or checkout setting.
+Missing/replaced storage fails before creating analysis data; there is no system-disk fallback.
+New profiles initialize on their first ordinary command, durably bind their own empty directory,
+and keep permanent compatibility paths. `storage show` remains passive.
 
 ```sh
 insight-cli permissions grant Update
@@ -29,7 +38,20 @@ user-selected outputs outside these trees keep their locations.
 
 Factory keeps profiles, permissions, IPC election/socket, migration-control metadata and
 application logs in current-user AppData. Secrets stay in the OS keyring. Credential/profile
-identities do not change. Updating/installing npm never migrates a profile automatically.
+identities do not change. Updating/installing npm preserves existing profile locations and does not select a disk on its own.
+
+## Select a default after an earlier migration
+
+For installations migrated with an older CLI, select their existing mounted base once:
+
+```sh
+insight-cli storage default --directory "/mnt/analysis volume" --json
+```
+
+This Update operation changes the installation default without moving existing data. Future
+profiles inherit it without repeating configuration. The base cannot be inside a profile data
+root or overlap Factory control storage. A base owned by another installation is rejected.
+A missing volume or replaced base/ownership marker is never adopted automatically.
 
 ## Move an existing profile
 
@@ -44,7 +66,7 @@ insight-cli storage migrate --directory "/mnt/analysis volume" --json
 insight-cli storage show --json
 ```
 
-Dry-run checks separation, destination contents, access, conservative capacity and quiescence
+Dry-run reports whether it would select the installation default and checks separation, destination contents, access, conservative capacity and quiescence
 without reserving/copying a migration. Source/destination/configuration roots cannot be equal
 or nested. Destination symlink roots, escaping source links, special files, unresolved links
 and inventories above one million entries or 128 directory levels are rejected. Internal
@@ -72,7 +94,9 @@ file, rechecks capacity and finishes the retained transaction. Source and destin
 anchor identities are bound durably. Missing/replaced volumes fail without creating a system-disk
 fallback; mount the original volume before resuming.
 
-Rollback restores retained source and the prior Factory setting. After activation it requires
+Rollback restores retained source and the prior Factory setting. The installation default stays
+selected because subsequent profiles may already use it; a resumed older migration cannot
+overwrite a newer default selection. After activation it requires
 an unchanged destination and a verified retained source. Native reopening or later findings can
 make rollback unsafe, in which case it refuses and preserves both copies. Use forward migration
 to another empty base after using the new location. A rolled-back destination remains for manual
@@ -97,3 +121,7 @@ before starting another. This release provides no nonempty-destination adoption,
 synchronization, live-DB snapshotting or network-filesystem guarantees. POSIX directory fsync
 is used. Windows has file fsync and rename/junction semantics; Node cannot fsync directories
 there, and internal symlinks can require OS privileges.
+
+Empty-profile initialization resumes automatically on its next command after interruption. Its
+retained source contains no analysis entries, so the CLI cleans only that owned empty backup
+automatically. Migration of existing data always retains its source for explicit cleanup.

package/skill-bundle/insight-artifacts/SKILL.md

@@ -3,7 +3,7 @@ name: insight-artifacts
 description: Retain a completed reverse-engineering evidence file or directory as an ordinary checkpoint using insight-cli artifacts save. Use after Ghidra or any external tool; preserve existing project formats and source of truth.
 ---
 
-# Insight Artifacts 0.3.0
+# Insight Artifacts 0.3.2
 
 If local help/status reports AppData or IPC access denied, retry that **read-only probe**
 with the agent host's normal permission escalation, then use that route for later authorized

package/skill-bundle/insight-artifacts/references/storage.md

@@ -1,10 +1,19 @@
 # Analysis storage and migration
 
 `storage show --json` reports effective profile storage, availability, active file/byte usage,
-exact included trees and retained migration. The default is Factory profile AppData. No
-checkout, environment or automatic disk fallback changes it. The non-secret setting is
-`analysisDirectory` in Factory's profile (`profile show` also displays it). Use storage commands
-to change it safely.
+exact included trees, retained migration and installation default base. Before selecting a
+base, storage starts in Factory profile AppData. `configure` and `migrate` select that base
+for subsequent new/empty profiles as well as moving the current profile. Add `--profile-only`
+to keep the installation default unchanged. The effective root appends `insight-cli/<profile>`.
+Initialized profiles keep their existing locations when the default changes; profiles with
+ordinary AppData analysis trees stay there until explicitly migrated.
+
+The per-profile non-secret `analysisDirectory` setting remains in Factory's profile. The
+installation default is bound storage-control metadata beside Factory's profile store, paired
+with ownership metadata on the chosen base. It is not an environment or checkout setting.
+Missing/replaced storage fails before creating analysis data; there is no system-disk fallback.
+New profiles initialize on their first ordinary command, durably bind their own empty directory,
+and keep permanent compatibility paths. `storage show` remains passive.
 
 ```sh
 insight-cli permissions grant Update
@@ -29,7 +38,20 @@ user-selected outputs outside these trees keep their locations.
 
 Factory keeps profiles, permissions, IPC election/socket, migration-control metadata and
 application logs in current-user AppData. Secrets stay in the OS keyring. Credential/profile
-identities do not change. Updating/installing npm never migrates a profile automatically.
+identities do not change. Updating/installing npm preserves existing profile locations and does not select a disk on its own.
+
+## Select a default after an earlier migration
+
+For installations migrated with an older CLI, select their existing mounted base once:
+
+```sh
+insight-cli storage default --directory "/mnt/analysis volume" --json
+```
+
+This Update operation changes the installation default without moving existing data. Future
+profiles inherit it without repeating configuration. The base cannot be inside a profile data
+root or overlap Factory control storage. A base owned by another installation is rejected.
+A missing volume or replaced base/ownership marker is never adopted automatically.
 
 ## Move an existing profile
 
@@ -44,7 +66,7 @@ insight-cli storage migrate --directory "/mnt/analysis volume" --json
 insight-cli storage show --json
 ```
 
-Dry-run checks separation, destination contents, access, conservative capacity and quiescence
+Dry-run reports whether it would select the installation default and checks separation, destination contents, access, conservative capacity and quiescence
 without reserving/copying a migration. Source/destination/configuration roots cannot be equal
 or nested. Destination symlink roots, escaping source links, special files, unresolved links
 and inventories above one million entries or 128 directory levels are rejected. Internal
@@ -72,7 +94,9 @@ file, rechecks capacity and finishes the retained transaction. Source and destin
 anchor identities are bound durably. Missing/replaced volumes fail without creating a system-disk
 fallback; mount the original volume before resuming.
 
-Rollback restores retained source and the prior Factory setting. After activation it requires
+Rollback restores retained source and the prior Factory setting. The installation default stays
+selected because subsequent profiles may already use it; a resumed older migration cannot
+overwrite a newer default selection. After activation it requires
 an unchanged destination and a verified retained source. Native reopening or later findings can
 make rollback unsafe, in which case it refuses and preserves both copies. Use forward migration
 to another empty base after using the new location. A rolled-back destination remains for manual
@@ -97,3 +121,7 @@ before starting another. This release provides no nonempty-destination adoption,
 synchronization, live-DB snapshotting or network-filesystem guarantees. POSIX directory fsync
 is used. Windows has file fsync and rename/junction semantics; Node cannot fsync directories
 there, and internal symlinks can require OS privileges.
+
+Empty-profile initialization resumes automatically on its next command after interruption. Its
+retained source contains no analysis entries, so the CLI cleans only that owned empty backup
+automatically. Migration of existing data always retains its source for explicit cleanup.

package/skill-bundle/insight-binary/SKILL.md

@@ -3,7 +3,7 @@ name: insight-binary
 description: Query structured PE, ELF and thin Mach-O headers, sections, imports and exports, or make an explicitly guarded new PE subsystem copy through insight-cli binary. Use for scoped binary structure, linkage and copy-only header edits without target execution.
 ---
 
-# Insight Binary 0.3.0
+# Insight Binary 0.3.2
 
 If local help/status reports AppData or IPC access denied, retry that **read-only probe**
 with the agent host's normal permission escalation, then use that route for later authorized

package/skill-bundle/insight-capture/SKILL.md

@@ -3,7 +3,7 @@ name: insight-capture
 description: Capture one explicitly authorized native program run, exact stdout/stderr and declared file snapshots through insight-cli capture, then inspect or compare retained reports without replay. Use for controlled input/output research, preserving original files and interrupted or unknown outcomes.
 ---
 
-# Insight Capture 0.3.0
+# Insight Capture 0.3.2
 
 If local help/status reports AppData or IPC access denied, retry that **read-only probe**
 with the agent host's normal permission escalation, then use that route for later authorized

package/skill-bundle/insight-cli/SKILL.md

@@ -3,7 +3,7 @@ name: insight-cli
 description: Choose and prepare reverse-engineering capabilities from the insight-cli toolbox for binary, managed-code and runtime investigations. Use to discover the appropriate tool or its packaged skill before installing native runtimes.
 ---
 
-# insight-cli 0.3.0
+# insight-cli 0.3.2
 
 If local help/status reports AppData or IPC access denied, retry that **read-only probe**
 with the agent host's normal permission escalation, then use that route for later authorized
@@ -39,6 +39,11 @@ installing npm binaries does not register them in an agent host. See
 Inspect `storage show --json` before relocating a profile. Use the supported
 [storage workflow](references/storage.md), preserving unknown operations and native folders.
 
+
+New targets import without full auto-analysis; `--analysis` opts in at first import.
+Reuse existing session/target selectors before opening another copy. Read [setup](references/setup.md)
+for explicit later analysis and passive first-open progress (`ghidra progress`).
+
 Use generated help as the syntax authority. Catalog metadata describes shipped capabilities;
 profile runtime readiness comes from the selected tool's `status`. Unavailable profile/IPC
 access means execution readiness is unknown. Preserve work and diagnose access before trying

package/skill-bundle/insight-cli/references/archive.md

@@ -0,0 +1,32 @@
+# Exchange private documentation with an archive
+
+Archive exchange is disabled until the selected Factory profile has an explicit `archiveUrl`.
+Use HTTPS for a remote service; local HTTP is supported for local services. URLs cannot contain
+credentials, query parameters or fragments. An optional bearer token is stored with
+`auth login --role archive --password-stdin`; it is a Factory secret and is never passed to
+Ghidra or the debuggee. `auth logout` clears this token as well as external server credentials.
+
+Use `ghidra archive ingest-function --address <entry>` or `ingest-program`, with the usual
+`--session` and `--target`. Both export the selected private view. `--version-label` supplies
+the archive version; its default is `unknown`. Internal project directories are not used as
+version labels. Bulk selection skips default function names unless `--include-default-named`
+is set; `--limit` bounds visited functions. Zero selects all, subject to the documented bound.
+`--dry-run` validates payloads and returns would-be counts without a network request.
+
+The service contract is `POST <archiveUrl>/v1/doc_archive/upsert` with JSON and an optional
+`Authorization: Bearer ...` header. The payload matches the pinned GhidraMCP builder: binary
+name, explicit version, function address, run/tool identity, name/prototype, calling convention,
+flags, matching hash/shape metadata, tags, named locals and instruction comments when present.
+The binary name is the logical target name. Each successful JSON response must contain a
+boolean `created` and a nonnegative integer `conflicts_enqueued`. Redirects are refused.
+
+Results retain created, updated, conflict, skipped and error counts. Archive conflict counts
+describe the external service's decisions; they do not resolve program merge conflicts.
+Use an optional stable `--request-id` when a response might be lost. A repeated ID returns
+the saved successful result or the retained uncertain outcome, without sending again.
+Each outbound payload identity and the source snapshot are retained before dispatch. Unknown
+external outcomes stay observable and do not block unrelated private research. A new request ID
+expresses another explicit submission; the facade does not assume the service can deduplicate it.
+
+Archive requests do not publish the program or alter another session. Developing or deploying
+the external archive service is outside this package; acceptance uses an owned contract fixture.