@eyeauras/insight-cli 0.2.4 → 0.3.1

package/skill-bundle/insight-cli/references/managed-runtime.md

@@ -0,0 +1,162 @@
+# Managed Ghidra runtime
+
+Use `ghidra install` for a complete compatible installation. Node 24+ is the bootstrap dependency;
+no existing Java, Ghidra, Homebrew, Gradle, compiler or Python MCP bridge is required. Factory
+profiles, permissions and OS secret storage remain in use. Follow the project's tool rules when
+it specifies an external installation or server.
+
+```sh
+insight-cli profile create local
+insight-cli --profile local permissions grant Update
+insight-cli --profile local ghidra install
+insight-cli --profile local ghidra status
+insight-cli --profile local ghidra open ./client.exe --session new --json
+```
+
+`download` caches the complete pinned Ghidra/JDK archives, without selecting or starting a runtime.
+`install` uses that cache or downloads missing archives, unpacks to a new stage, checks JDK 21 and
+Ghidra 12.1.2, decompiles a known x86 function and starts a disposable local Ghidra Server. The
+server probe authenticates its identity and reader/publisher permissions. Selection changes only
+after all checks pass. The bridge and helper sources come from the version-matched npm package.
+A failed install preserves its stage/diagnostics and the old selection. Retrying uses a fresh stage;
+completed cached archives are reused. A later install/doctor/uninstall authenticates and stops
+any leftover disposable probe server before proceeding; an unverified live identity blocks recovery. Interrupted partial downloads are never used as complete files.
+
+On Windows, long Ghidra Java classpaths use an owned per-execution argument file, retained with
+the process diagnostics. `javac` files use UTF-8; `java` launcher files use the Windows system
+code page. Java 21's launcher still requires paths representable in that code page. Unmappable
+characters fail before launch rather than selecting different files through lossy conversion.
+
+`status` without scope is passive: selection, paths, missing components, installations, retained
+stages, recorded checks and live process receipts. It works before installation. It does not start
+Java or create a research workspace. `status --session S --target T` retains the scoped live health
+check. `server status` also works without an installed runtime and explains missing prerequisites.
+`doctor` explicitly runs disposable native decompiler/server probes and checks macOS LLDB Python.
+It never imports a research target or publishes research changes. Readiness recorded by a doctor
+run includes its runtime fingerprint; status identifies whether that record matches the selection.
+
+## Local archives and external installations
+
+```sh
+insight-cli --profile local ghidra download
+insight-cli --profile local ghidra install --offline
+insight-cli --profile local ghidra install --archive ./ghidra.zip
+insight-cli --profile local ghidra install --archive ./ghidra.zip \
+  --java-archive ./jdk.tar.gz --debugger-archive ./lldb-python.tar.gz --offline
+insight-cli --profile local ghidra install --executable /tools/ghidra/ghidraRun
+insight-cli --profile local ghidra install --executable /tools/ghidra \
+  --java /tools/jdk/bin/java --debugger-archive ./lldb-python.tar.gz --offline
+```
+
+`--executable` accepts the actual Ghidra launcher (`ghidraRun[.bat]`, or
+`support/analyzeHeadless[.bat]`) or installation directory. It needs the complete compatible
+installation, including host native components. A target EXE is not a Ghidra launcher.
+Common Homebrew launcher wrappers are resolved through the adjacent complete `libexec` tree.
+The external Ghidra tree is never modified or deleted. Java is delivered automatically unless
+`--java` or `--java-archive` is supplied. Legacy profile `java`/`ghidraHome` configuration still works
+when no explicit selection exists; an explicit selection takes precedence and never silently
+falls back to profile paths after failure or uninstall.
+
+Local archives are caller-selected inputs, consumed into owned hash-addressed copies before
+extraction so later source edits cannot change the installed bytes. Optional `--archive-sha256` and
+`--java-archive-sha256` and `--debugger-archive-sha256` check the expected bytes; the actual digests are recorded in the installation
+identity. `--offline` prohibits network acquisition: provide/cache every required archive. On macOS,
+an official Ghidra zip also needs the pinned prebuilt native archive in cache. The managed macOS
+distribution already includes these natives. Executable modes are preserved; paths, links and
+expanded sizes are checked during portable Node extraction. Downloads use exact assets retained
+in `iXab3r/insight-cli` GitHub Releases, with hashes and sizes pinned in the installed package.
+There is no runtime upstream/latest fallback; supplied archives and verified cache support offline use.
+No external unzip, tar or Python executable is needed for extraction.
+
+## Server, process and data ownership
+
+The Ghidra distribution includes Ghidra Server. It uses the selected JDK and immutable tool code;
+its repository, certificates, credentials and process settings are separate profile data.
+Ordinary `open` starts it automatically. `server start` explicitly starts/enables it, and
+`server stop` stops the identified owned server after all contexts are closed. It refuses to stop
+a server under live clients. A later open can start it again; explicit `disconnect` disables shared
+operations until `connect`/`start`. `server connect/disconnect` retain their connection-management API.
+An external server remains configured through profile server/repository/account fields and Factory
+secrets; `server stop` cannot stop that external service.
+
+Code/cache/installation receipts live under configured [analysis storage](storage.md) `runtime/`; research remains under
+`workspace/`, and saved files under `materials/`. One selected immutable installation serves many
+isolated JVM contexts; each has its own projects, home, settings, cache/temp and authenticated
+endpoint. No per-agent copy of the Ghidra code distribution is required. This is process and data
+isolation; it does not restrict arbitrary user scripts to an OS security sandbox.
+
+Close scoped contexts and stop the owned server before selecting/reinstalling/removing a runtime.
+A live receipt conservatively blocks these operations; it never authorizes killing a PID.
+Download and doctor can run without switching the current runtime. Runtime commands serialize
+within the Factory owner. Changing a selected runtime invalidates cached backend handles, without
+removing saved research. There is no automatic version migration or floating upstream upgrade.
+
+```sh
+insight-cli --profile local ghidra close --session S --target T
+insight-cli --profile local ghidra server stop
+insight-cli --profile local permissions grant Destructive
+insight-cli --profile local ghidra uninstall
+# Optional cache deletion; research and external installations remain preserved:
+insight-cli --profile local ghidra uninstall --purge-cache
+```
+
+Uninstall removes only selected owned installation files. It preserves the selection as an
+uninstalled receipt, so later research reports a missing runtime instead of changing bindings.
+Archives remain reusable unless `--purge-cache` is selected. It removes recorded archives for
+this installation, preserving other tools' cache and unrecorded legacy entries. Reinstalling the same archives restores
+the same runtime identity. Sessions, private snapshots, unresolved publication journals, server
+repositories and artifacts survive. Uninstall does not resolve an uncertain merge or replay it.
+
+## Process inventory and recovery
+
+```sh
+insight-cli --profile local tools processes --tool ghidra
+insight-cli --profile local tools processes show <process-id>
+insight-cli --profile local tools processes stop <process-id>
+insight-cli --profile local tools processes kill <process-id>
+```
+
+These IDs describe executions, not new research selectors. Context records include the existing
+session/target; server, GUI, debugger and helper roles remain separate. `stop` saves a selected
+Ghidra context through its ordinary close path. Stopping a server requires closed contexts.
+`kill` requires Destructive and explicitly interrupts verified owned work; it does not prove a
+merge/save completed. Live debugger cleanup goes through the owning GUI so inferior termination
+can be verified. Research and unknown journals are retained.
+
+After an owner crash, inventory reconnects to authenticated owned endpoints without re-executing
+research. macOS process birth times alone cannot prove recovered ownership; an ambiguous process
+stays `unverified` and is not signalled. Original child handles and authenticated tool identities
+provide the supported stop/kill authority. This is lifecycle management, not an OS security sandbox.
+
+## Sources and host boundary
+
+The catalog pins Ghidra 12.1.2 and Temurin JDK 21.0.11+10. macOS uses public Homebrew-built Ghidra
+bottles with native components (macOS 14+, ARM64 or x64); no installed Homebrew is used. Linux x64
+and Windows x64 use the official Ghidra zip and Temurin archive. The installed `runtime/tool-catalog.json` pins mirror assets; repository
+`scripts/tool-distributions/` recipes retain upstream provenance. Published tool releases include
+original licenses/notices and required source/build companions, independent of CLI releases.
+Unsupported platforms fail explicitly and may use compatible external profile paths. Native
+acceptance for this delivery is macOS ARM64; catalog availability is not Windows/Linux native proof.
+
+The host provides Node/npm, OS frameworks, display/keychain access and debugger authorization.
+macOS LLDB and its embedded Python come from Apple's developer tools; they are OS prerequisites,
+not downloaded third-party Python dependencies. `doctor` reports a missing host debugger as a partial
+failure even when static analysis/server pass. No root installation, developer-tools installer,
+Gatekeeper disabling, shell-profile edit or global Java/Python selection is performed. Ghidra GUI
+agents receive private copies of the Ghidra SDK's pinned debugger Python wheels.
+
+## Managed debugger dependency
+
+On macOS 15+ ARM64, download/install also prepares pinned LLDB 23.1.3 with its own
+Python 3.15 and native library closure. It is a private Ghidra dependency; the separate
+`insight-cli lldb` application retains its own installation. `--debugger-archive` supplies
+the exact pinned debugger archive for offline installation, including an external Ghidra
+selection. Status reports this dependency and doctor probes its actual Python interpreter.
+GUI startup prepares it for legacy profiles as needed. The backend does not use Homebrew
+or Python from Apple developer tools. OS debugger authorization is still a host prerequisite.
+
+A GUI context pins the verified debugger receipt. Its supervisor verifies those code and
+library bytes again before launching LLDB. Close contexts and stop the local server before
+changing/removing the Ghidra runtime; uninstall removes this owned dependency while retaining
+research and external installations. Existing running GUI contexts must be closed/reopened
+to adopt a different backend. Other host debugger profiles retain their declared host requirements.

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

@@ -0,0 +1,79 @@
+# Continue saved work
+
+Retain the session/target returned by initial open. Continue the tuple through
+`insight-cli ghidra open --session <id> --target <id> --json`. Saved private snapshots and
+pending scalar comparisons persist independently of a backend process. Reopening preserves
+private work; it does not silently receive a newer shared version.
+
+First-import recovery uses the same scoped `ghidra open` or the original request ID/input.
+Import/analysis writes a private snapshot and completion receipt before any initial publication.
+If its worker is still running, continuation reports busy; wait and continue the same scope.
+If that worker stopped before completing its receipt, continuation can repeat private analysis
+from the immutable input while retaining previous attempts. A completed snapshot is reused.
+Initial publication first creates a uniquely named staging object. A separate read-only process
+verifies its complete saved DB buffers before a conditional server move to the absent canonical
+path. It never checks in a new version of an existing canonical item. Lost promotion replies
+are reconciled against the retained identity, one-version history and complete saved buffers.
+Interrupted staging objects remain retained and can be replaced by another private stage;
+they are not adopted as the canonical model. Foreign or mismatched canonical state stays blocked.
+An older direct create that is provably owned and left only an incomplete `<Recovered>` entry
+can be moved aside without deletion; its bytes and original receipt remain preserved.
+
+Legacy first-import failures are also recoverable in the original profile. Continuation first
+establishes that the old owned bootstrap worker has ended, then uses an authoritative repository
+probe. An absent canonical item permits private preparation; an existing first version requires
+independent readback. The old project, intent and original session/target remain preserved.
+
+If a response was lost, inspect `sessions status <session> --target <target>`. Never infer
+`applied` from a connection failure. A changing command's optional request ID binds one effective
+intent inside the profile. Repeating the same ID/input retrieves its recorded outcome or
+unresolved state; changing input under that ID fails. Without an ID, calls are new intentions.
+
+An unknown or partial effect retains its request intent, snapshots and native stage. Open the
+same tuple to reconcile supported outcomes. A committed merge is verified against its recorded
+server version and complete saved buffers through independent read authority; it is never
+checked in again merely because its response was lost. Until verification succeeds, publication
+for this shared target is blocked across sessions. Saved private work remains retained.
+
+Scalar reconciliation observes and saves an already present effect; it does not execute the
+setter again. Supported structural/function edits retain a candidate snapshot after an incomplete
+response; continuation can verify every requested effect in that immutable snapshot and adopt it
+without replay. If the complete result cannot be established, the candidate and previous saved
+private view remain retained. An unproved program/script/external outcome remains unresolved. Preserve the profile
+storage and credential store. Do not delete another session's project, stop a process by guessed
+PID/port, or blindly repeat a script/external action to turn uncertainty into success.
+
+The older prototype's `workers`, `findings`, `integrate` and batch `recover` commands are not the
+public facade API. Its coordinator journals remain separate and are never silently migrated.
+
+A lost UI navigation response can be verified from the live authenticated cursor without another
+goto. If its original owned GUI process has exited, continuation reports the uncertain UI action
+as disconnected and retains saved program work. It does not recreate the old cursor or re-enable
+a previous prompt policy. Other unproved live UI effects remain retained until their outcome is
+established or the original process is known to have ended.
+
+## Abandon an uncertain private program attempt
+
+A post-mutation save timeout does not repeat the script or issue another save in the
+error handler. Status exposes the original request identity and retained phase/budget.
+Arbitrary script effects are never inferred from metadata or from an unverified DB.
+After inspecting the retained attempt, explicitly stop only its verified owned worker
+(`tools processes`, then `tools processes kill <process>` if required). Resume the
+last acknowledged private snapshot with:
+
+```sh
+insight-cli permissions grant Destructive
+insight-cli ghidra abandon --session <session> --target <target> \
+  --request-id <original-request> --acknowledge-unknown-effects --json
+insight-cli ghidra open --session <session> --target <target> --json
+```
+
+Abandon requires exactly one unresolved private program operation, an unchanged verified
+previous snapshot/generation, a stopped original worker and no active publication or live
+debugger. It retains the native project, candidate artifacts, original intent/execution and
+previous diagnostic result. Its terminal request is `failed` / `state: abandoned` with
+`outcome: unknown`; no effect is marked applied. Repeating abandonment retrieves the same
+result. Earlier saved private edits remain pending. The original changing request ID cannot
+execute again. Abandoning never undoes external effects or establishes what an arbitrary
+script did; the acknowledgement explicitly accepts that uncertainty. Publication recovery,
+initial import, UI and debugger attempts use their own protocols and cannot use this command.

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

@@ -0,0 +1,98 @@
+# Setup
+
+Inspect `storage show --json` and read [analysis storage](storage.md) before moving databases.
+Use `storage configure` for an empty profile or `storage migrate` for existing work. Factory
+control metadata and keyring identity stay in their original locations.
+
+Use Node 24+ and `ghidra install` to deliver Ghidra 12.1.2, JDK 21, native components and
+server support. See [managed runtime](managed-runtime.md) for download/install/offline archives,
+external executable paths, status/doctor and safe removal. Existing Factory profile `java` and
+`ghidraHome` paths remain supported when no managed/external selection exists.
+The package contains the verified GhidraMCP 7.0.0 bridge, its Apache-2.0 license/notice and
+artifact provenance. Its pinned functionality catalog is from source
+`57e37a8bf388b1279cff46378f85be1554548f61`, with SHA256
+`7084e2fda16dc779dd05398e48821ff3f9ace4d32757ea143b257b39689e5fbd`.
+`mcpJar` optionally selects another copy of those exact verified bytes. Runtime startup needs no
+bridge/Factory source checkout or Python MCP bridge. Packaged native helper sources compile
+against the installed Ghidra/JDK.
+
+Omitting `server` enables owned local startup. The facade creates profile storage, a private
+repository and distinct read-only/publisher accounts with random credentials in Factory's secret
+store. It manages isolated headless contexts and introduces GUI mode on demand.
+
+For an external server profile, configure `server` (`ghidra://host:port`), `repository`,
+`readerUser` and `publisherUser`. They are distinct accounts with actual read-only and write
+permissions respectively. Store each password using `auth login --role reader|publisher
+--password-stdin`. Passwords are stdin/secret-store values, never profile JSON or argv values.
+Connecting does not transfer ownership of that external server or allow the facade to stop it.
+
+Factory's Update permission is initially disabled. Enable it through `permissions grant Update`
+in the selected profile before creating contexts or editing. Research scope is explicit; local
+skill discovery and help require no authentication or native process startup.
+Deletion and replacement commands also require `permissions grant Destructive`.
+
+All target bytes, snapshots, journals, projects and process receipts derive from the selected
+profile's AppData. Stop the owner through `ipc-server stop` before changing its code/runtime
+configuration. Restoring a saved context preserves its private view. Server settings and initial
+loader settings remain bound to the target/workspace, so changing those cannot silently replace
+retained work. This revision conservatively protects retained profile research state from deletion.
+Runtime identity covers installed Ghidra code, language/compiler data, native modules and Python
+inputs together with JDK tools, modules and configuration. Generated Python caches are isolated.
+Changing those runtime inputs requires stopping the old owner before continuing with the new build.
+
+Native acceptance separates macOS GUI/LLDB workflows from selected headless Windows/Linux
+SDK, Version Tracking and FID/BSim workflows. Native Windows/Linux debugger/GUI acceptance
+remains deferred. The ordinary CI lane stays offline; disposable native CI is explicit.
+
+On macOS 15+ ARM64, `ghidra install` delivers an owned LLDB/Python debugger backend;
+OS debugger authorization remains required. Other host profiles need their supported debugger. Its
+Ghidra Python dependencies are prepared from the installed SDK wheels into owned GUI storage.
+`debuggerPython` optionally configures a Python-backed offer; `windbgDir` configures the Windows
+debugger runtime directory when relevant. These are runtime profile settings, not research scope.
+
+Archive exchange is opt-in through `archiveUrl`; its optional token uses Factory secrets.
+See [archive](archive.md) for the service contract and submission recovery behavior.
+
+## Native operation budgets
+
+Profile `initialImportSeconds` defaults to 3600 (1–86400 seconds); `saveSeconds`
+defaults to 120 (1–3600 seconds). Configure them with `ghidra budgets set
+--initial-import-seconds 7200 --save-seconds 300`; `ghidra budgets show` reads effective values.
+This uses Factory ProfileStore without invalidating research or stopping native contexts.
+Active requests retain their original budget. Generic `profile set` remains guarded for
+profiles containing research; initial profile creation also accepts these fields. Both are execution policy, independent
+of immutable target/load identity. Save and packed snapshot export use the save budget;
+discovery and ordinary HTTP queries keep their 30-second budget. Each native request has
+its own budget, not a total command deadline. Cancellation remains independent.
+
+After an import timeout, wait for the original worker to end, raise its budget and continue
+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/skill-bundle/insight-cli/references/storage.md

@@ -0,0 +1,99 @@
+# 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.
+
+```sh
+insight-cli permissions grant Update
+insight-cli storage show --json
+insight-cli storage configure --directory "/mnt/analysis volume" --json
+```
+
+`configure` requires no existing analysis entries. With existing data use `migrate`.
+The directory is a **base**: the effective root appends `insight-cli/<profile>`, preserving
+profile isolation. Choose an ordinary empty destination profile directory on a mounted local
+filesystem. Spaces and Unicode are supported. Factory restricts the dedicated destination root to the
+current user, including a Windows ACL; a filesystem that cannot apply this protection fails
+before copying.
+
+The complete `workspace`, `materials`, `temp` and `runtime` trees move: immutable inputs,
+artifact/candidate snapshots, workspace SQLite DB/WAL, native private project/context DBs,
+local Ghidra Server repositories, operation/publication/import journals, debugger traces,
+process captures, exports, native helper compilation and verification working data.
+**Runtime installations, acquisition caches, selections and process receipts move too**;
+installation staging and activation must share a filesystem. External tool installations and
+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.
+
+## Move an existing profile
+
+Finish changing commands, close native contexts, and stop this profile's owned server/tool
+processes through ordinary CLI commands. Inspect `tools processes --json`. Unverified lifetimes
+also block migration. Do not kill guessed PIDs or stop other profiles to make preflight pass.
+Factory retains IPC ownership and command admission; other profiles can keep working.
+
+```sh
+insight-cli storage migrate --directory "/mnt/analysis volume" --dry-run --json
+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
+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
+links retain their exact target strings. Preflight does not reserve space; concurrent disk use
+can still cause a copy failure.
+
+Migration durably reserves its journal, hashes stable source bytes, streams/syncs the copy,
+independently hashes destination bytes and rechecks the source. Only then does it replace source
+trees with permanent compatibility links and commit the Factory setting. Original trees are
+renamed into `.storage-retained/<migration>` on their original volume. Copy/activation never
+deletes them, including on failures. Existing IDs, requests, journals, candidate snapshots and
+receipts retain exact bytes. Compatibility paths preserve old absolute references: do not remove
+those links or their profile/source ancestors manually after migrating.
+
+## Interruptions, uncertainty and retention
+
+```sh
+insight-cli storage resume --json
+insight-cli storage rollback --json
+```
+
+Ordinary research freezes during incomplete copy/activation/rollback/cleanup. `show` and Factory
+profile inspection remain available. Resume verifies completed files, recopies an incomplete
+file, rechecks capacity and finishes the retained transaction. Source and destination filesystem
+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
+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
+inspection/removal and is never automatically adopted. Cleanup permanently disables rollback.
+
+Unknown script/publication effects do **not** need abandonment before migrating a stopped
+profile. Migration starts no worker, replays no script/check-in and marks no unknown outcome
+applied. Inspect the original request after migrating; existing [recovery](recovery.md)
+restrictions and independent readback requirements still apply.
+
+After independent native reopen and saved-file readback, free retained source explicitly:
+
+```sh
+insight-cli permissions grant Destructive
+insight-cli storage cleanup --json
+```
+
+Cleanup verifies retained bytes, records irreversible intent, then deletes only that owned
+backup. Interrupted cleanup continues through `storage resume`; rollback is already disabled.
+Compatibility links, receipts and manifests remain. Clean or roll back the current migration
+before starting another. This release provides no nonempty-destination adoption, reverse
+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.

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

@@ -3,7 +3,7 @@ name: insight-die
 description: Classify unknown executable or container inputs by format, architecture and compiler/runtime/packer signatures with Detect It Easy before choosing managed or native analysis. Use insight-cli die for static triage and preserve scan uncertainty.
 ---
 
-# Insight Detect It Easy 0.2.4
+# Insight Detect It Easy 0.3.1
 
 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-dnspy/SKILL.md

@@ -3,7 +3,7 @@ name: insight-dnspy
 description: Debug a managed Windows EXE at an IL breakpoint and read primitive arguments, or change one expected IL Int32 constant in a new assembly copy through insight-cli dnspy. Use when C# decompilation needs observed execution or a controlled binary edit.
 ---
 
-# Insight dnSpyEx 0.2.4
+# Insight dnSpyEx 0.3.1
 
 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-dotnet-dump/SKILL.md

@@ -3,7 +3,7 @@ name: insight-dotnet-dump
 description: Capture a managed heap dump or inspect compatible .NET dumps with SOS to recover waiting stacks, objects, fields and retention evidence.
 ---
 
-# Insight .NET Dump 0.2.4
+# Insight .NET Dump 0.3.1
 
 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-dotnet-stack/SKILL.md

@@ -3,7 +3,7 @@ name: insight-dotnet-stack
 description: Inspect live managed thread stacks to identify active or waiting work in an explicitly selected .NET process without taking a dump.
 ---
 
-# Insight .NET Stack 0.2.4
+# Insight .NET Stack 0.3.1
 
 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-dotnet-trace/SKILL.md

@@ -3,7 +3,7 @@ name: insight-dotnet-trace
 description: Collect and inspect bounded .NET EventPipe traces to identify sampled thread work, waits or runtime activity; distinguish wall-clock samples from CPU consumption.
 ---
 
-# Insight .NET Trace 0.2.4
+# Insight .NET Trace 0.3.1
 
 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-frida/SKILL.md

@@ -3,7 +3,7 @@ name: insight-frida
 description: Observe native call arguments/results or inspect runtime modules and exports in an explicitly selected authorized process with bounded Frida scripts. Use insight-cli frida to corroborate static findings with actual execution on macOS ARM64.
 ---
 
-# Insight Frida 0.2.4
+# Insight Frida 0.3.1
 
 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-ghidra/SKILL.md

@@ -3,7 +3,7 @@ name: insight-ghidra
 description: Inspect or edit native binaries with Ghidra through insight-cli; use isolated contexts, multi-agent merge/refresh, server, GUI or debugger workflows. Choose this for static native behavior and references, not C# recovery from managed IL.
 ---
 
-# Insight Ghidra 0.2.4
+# Insight Ghidra 0.3.1
 
 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
@@ -17,6 +17,32 @@ session/cell ID, await that same execution with the host's wait/poll facility un
 status and read its stdout/stderr. An empty first chunk is not a lost CLI response. Do not
 start another open or repeat a CPU mutation while the original command is still running.
 
+
+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.
+
 Use `ghidra status` to inspect runtime readiness; `ghidra install` delivers the pinned runtime.
 For static managed C#/IL research, locate `insight-cli skill insight-ilspy`.
 For owned process inventory use `tools processes`; `stop` saves Ghidra contexts, while

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

@@ -1,7 +1,7 @@
 # Save ordinary research materials
 
 `insight-cli artifacts save <path> --json` saves a file or a settled directory tree in
-the selected profile's AppData. It needs Factory Update permission and does not require
+the selected profile's [analysis storage](storage.md), which defaults to AppData. It needs Factory Update permission and does not require
 Ghidra, Java, authentication, target/session selectors or evidence metadata. Relative input
 paths resolve against the caller's working directory. Use `--help` for generated syntax.
 

package/skill-bundle/insight-ghidra/references/managed-runtime.md

@@ -79,7 +79,7 @@ operations until `connect`/`start`. `server connect/disconnect` retain their con
 An external server remains configured through profile server/repository/account fields and Factory
 secrets; `server stop` cannot stop that external service.
 
-Code/cache/installation receipts live under profile AppData `runtime/`; research remains under
+Code/cache/installation receipts live under configured [analysis storage](storage.md) `runtime/`; research remains under
 `workspace/`, and saved files under `materials/`. One selected immutable installation serves many
 isolated JVM contexts; each has its own projects, home, settings, cache/temp and authenticated
 endpoint. No per-agent copy of the Ghidra code distribution is required. This is process and data

package/skill-bundle/insight-ghidra/references/setup.md

@@ -1,5 +1,9 @@
 # Setup
 
+Inspect `storage show --json` and read [analysis storage](storage.md) before moving databases.
+Use `storage configure` for an empty profile or `storage migrate` for existing work. Factory
+control metadata and keyring identity stay in their original locations.
+
 Use Node 24+ and `ghidra install` to deliver Ghidra 12.1.2, JDK 21, native components and
 server support. See [managed runtime](managed-runtime.md) for download/install/offline archives,
 external executable paths, status/doctor and safe removal. Existing Factory profile `java` and
@@ -65,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.