@eyeauras/insight-cli 0.2.0 → 0.2.1

package/skills/insight-ghidra/references/managed-runtime.md

@@ -0,0 +1,157 @@
+# 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.
+
+`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 profile AppData `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/skills/insight-ghidra/references/native-workflows.md

@@ -0,0 +1,112 @@
+# Selected native SDK workflows
+
+These commands extend the pinned MCP catalog. All program calls select both `--session` and
+`--target`; API callers use the same Factory command paths. Use generated help for flags.
+Programs remain private until explicit `ghidra merge`. Every new program edit is a complex
+change: saved-state verification is required, and a diverged shared base retains a conflict.
+`refresh` does not silently overwrite either complex version. Program edits require Destructive
+permission. File/database creation and VT decisions require Update; reads require ReadOnly.
+
+## Compare and edit a private program
+
+`ghidra changes compare --other-target <id> --other-session <id>` compares immutable saved
+contexts with native ProgramDiff. Choose `--categories '["bytes","comments","symbols"]'`;
+other supported categories are code_units, functions, references, context and properties.
+Results retain address ranges and completion flags. This does not run a universal DB merger.
+
+`ghidra memory patch-bytes --address 0x180000000 --expect-hex 9090 --bytes-hex 9091`
+requires equal lengths of 1–4096 bytes and clears overlapping listing. `assembly preview` takes
+`--instructions '["NOP"]'`; `assembly apply` also requires exact `--expect-hex`. Assembly uses
+the selected program's language and processor context. It does not rebuild executable files.
+
+`memory block-state --name <block>` returns current layout and a full digest for initialized
+blocks up to 16 MiB. `split-block` and `move-block` require that digest, size and original start;
+`join-blocks` requires both sizes/digests and compatible adjacent blocks. No uninitialized or
+oversized-block edit is implied. `processor-context read|set|clear` addresses a named register
+and a range of at most 65536 bytes. Read distinguishes explicit state from compiler defaults.
+
+`namespaces list|create|update|delete` supports ordinary namespaces/classes; deletion requires
+an empty container. `externals` supplies create/update/delete-library and create/update/delete-location.
+Deletion refuses retained dependencies. It does not recursively erase referenced program state.
+
+`decompiler ir --address <function> --simplification normalize --max-ops 1000` returns typed SSA
+operations, varnodes, address spaces, sizes and block IDs. Options are known Boolean keys:
+eliminate_unreachable, respect_read_only, infer_constant_pointers, split_structures, split_arrays.
+Native timeout is 1–120 seconds. `completed` describes decompilation; `ir_complete` separately
+reports a truncated operation list. The result is a bounded view, not a serialized HighFunction graph.
+
+## Loader, exporter and type archives
+
+`ghidra formats loaders --input <file>` consumes immutable bytes and lists actual installed
+loader IDs, supported language/compiler specifications and native option definitions.
+`ghidra open <file> --session new --loader BinaryLoader --language x86:LE:64:default
+--loader-options '{"Base Address":"0x10000","File Offset":"0x2","Length":"0x6"}'`
+selects a loader explicitly. Primitive options, native address and HexLong options are converted
+and validated; unsupported complex option classes fail explicitly. One program belongs to a target.
+
+`formats exporters` lists compatible native exporters and their options. `formats export
+--exporter 'Raw Bytes' --ranges '[{"start":"0x10001","end":"0x10003"}]'
+--output-directory <new-directory>` requires a format supporting restricted address sets.
+All output/companion files are hashed and retained. Existing destinations are not overwritten.
+Native completion receipts permit a repeated request ID to recover completed bytes without
+another export. An incomplete/uncertain export cannot be replayed blindly.
+
+`types define-layout --path /Owned/Record --packing 1 --fields
+'[{"name":"flags","type":"uint","bit_size":3},{"name":"value","type":"ushort"}]'`
+uses native structures and bitfields. Packing/alignment accept -1, zero or powers of two through
+64; explicit byte offsets require packing -1. There are at most 256 fields. `types layout` returns
+native source archive/universal IDs and bounded field/setting records. `types set-settings --path
+/Owned/Number --settings '{"Format":1}'` uses actual definition names and native enum choices;
+null clears an explicit setting. Inventory the type first; definitions differ between native types.
+
+`types archive-export --types '["/Owned/Record"]' --output-directory <new-directory>` creates a
+real GDT. `types archive-import --input <file.gdt> --types '["/Owned/Record"]'` consumes an
+immutable archive up to 64 MiB and checks saved layout/source identity. A conflicting existing
+layout is rejected. `types create-struct --replace-placeholder` replaces only an empty structure.
+
+## Version porting and library identification
+
+`version-tracking create --source-target <id> --source-session <id>` creates a persistent native
+VT session inside the destination research scope. The returned tracking ID owns the exact saved
+source/destination snapshots. `list`, `matches --tracking <id>` and `markup --tracking <id>
+--source-address <address> --destination-address <address>` retain native correlator/score/markup
+provenance. Exact function bytes and duplicate instruction correlators are selected; instruction
+matching can ignore operands. Ambiguity is retained. Unmatched means no association in these
+selected policies, not proof of no equivalent function. Inputs are limited to 10000 functions;
+correlation has a 60-second monitor budget, match pages have at most 1000 rows.
+
+`decide` explicitly accepts, rejects or resets an association; native one-to-one constraints apply.
+Decisions survive owner replacement. Markup is inspected before ordinary facade edits transfer
+selected changes. No automatic markup application/publication is performed. Context-changed flags
+warn when current programs differ from the VT snapshots. Unknown decisions block further decisions
+on that object until reconciliation; the same request ID never blindly repeats a native effect.
+
+`libraries build-fid --library <name> --library-version <version> --output-directory <new-directory>`
+creates a genuine native FID database. `libraries fid-query --database <file.fidb> --function <entry>
+--threshold 1` reports native scores, library/version/variant, database digest and no-match semantics.
+`build-bsim --library <name> --output-directory <new-directory>` creates embedded native BSim/H2;
+`bsim-query --database <database.mv.db> --function <entry> --similarity 0.9` reports signature version,
+similarity and significance. Required SDK components are supplied by the pinned Ghidra install;
+there is no external database service to provision for these local workflows. Inputs are bounded to
+1000 functions, output is bounded, and scores are not calibrated probabilities. Query databases
+are consumed into private immutable storage; the caller's file is unchanged.
+
+## Live target and retained trace
+
+`debugger write-memory --address <dynamic-address> --expect-hex <bytes> --bytes-hex <bytes>`
+and `write-register --register <name> --expect-value <hex> --value <hex>` require a stopped,
+selected live target at its current live time. They refresh from the target before and after the
+write. Preconditions are read-before-write checks, not atomic compare-exchange. Register width
+is exact. These live effects do not enter program publication. A lost write response remains
+uncertain and is never replayed, even when trace bytes subsequently show the requested value.
+The owned copy of Ghidra 12.1.2's Python adapter corrects its SBProcess memory-write call; the
+installed SDK/wheel remains unchanged and runtime fingerprint checks still apply.
+
+`debugger timeline --limit 100` returns snapshot keys/times/schedules and continuation.
+`objects --limit 100 --max-scan 10000` returns persistent object IDs, schema, path and lifespan
+at a selected snap. `object-values --object-id <id> --key <exact-key>` reads one key, optionally
+over at most 1000 snapshot keys. Values preserve address/object-reference types and 64-bit integers;
+unknown Java value kinds are explicit. Object iteration is budgeted, paths replace the owned
+staging root with `@target`, and IDs remain scoped to the selected trace. `schedule --schedule <time>`
+parses/validates native schedules and reports `executed: false`. It does not execute emulation.
+Saved trace queries remain available after disconnect; live execution is never resurrected.

package/skills/insight-ghidra/references/query-semantics.md

@@ -0,0 +1,96 @@
+# Query semantics and work limits
+
+Read operations return observations with their scope. A successful command can report a **partial
+scan** or a **stopped emulation**: inspect the completion fields before drawing conclusions.
+A backend placeholder/unavailable status is an error, including when nested in an otherwise
+successful response. Generated help describes the facade's implementation, not an upstream stub.
+
+## Static reachability and constants
+
+`analysis find-dead-code --function-name <name-or-entry>` walks the selected function's decoded
+basic blocks. `complete`, `unresolved_flow`, `scan` and `findings` distinguish a completed static
+CFG result from a budget stop or unresolved indirect flow. Incomplete/unresolved analysis does
+not classify blocks as unreachable. This is not a runtime-execution proof or an analysis of
+undecoded bytes outside the function body.
+
+`analysis detect-crypto-constants` searches initialized memory for the versioned exact signatures
+listed under `database`. Matches identify constant-table candidates, not proof of cryptographic
+execution. `--max-bytes` defaults to 1 MiB and is capped at 16 MiB. `complete: false` returns
+`next_address`; continue with `--scan-from`, or increase the budget if the remaining lookahead
+cannot fit. `search-byte-patterns` has the same byte budget/continuation behavior. Wildcard byte
+pairs use `??`; an explicit mask uses `x`/`?`. Several signatures at one address are grouped in
+`signatures`, with a primary `signature`.
+
+## Types, prototypes and entries
+
+`types get-valid-data-types` lists actual program types and successfully resolved builtins,
+including category/path, size, alignment and source. It does not advertise a hard-coded list of
+Windows names as installed types. `types validate-data-type` reports `resolved` and `diagnostics`.
+Resolution is distinct from whether a particular memory location can accept that type.
+
+`types validate-function-prototype` uses Ghidra's signature parser and an isolated temporary type
+manager. It returns `valid`, `signature`, `diagnostics` and `persisted_changes: false`. Unsupported
+compiler conventions and parse failures cannot pass as valid. The parser supports Ghidra's C
+signature syntax; it is not a general C++ compiler. Validation checks the program modification
+counter and does not persist types or mutate the function.
+
+`listing get-entry-points` separates `entry_points` with Ghidra external-entry metadata from
+`candidates` inferred from names or image base. An external entry designation is metadata;
+the image base and a conventional `main` name are not proof of an OS startup address.
+
+## Structured and bounded reads
+
+Globals are records containing `address`, `name`, `type`, `type_path`, `size`, `xrefs`, `named`,
+`typed`, namespace and symbol provenance. Parsing display text is unnecessary.
+
+Facade-owned global/string/type/instruction scans accept `--max-scan` (default 100000, maximum
+200000 visited inputs), `--timeout-seconds` (1–30), `--limit` and `--offset`. Output paging does not
+increase the work budget. `scan.complete: false`, `truncated: true` and `total_known: false` mean
+`total` counts only the scanned prefix; absence from that prefix is not a negative whole-program
+finding. Narrow the query or raise its budget within the declared bound. Oversized string units
+also stop a scan rather than silently claiming complete coverage. Returned string values are
+bounded; check truncation fields.
+
+Bounded string/instruction regex search supports literals, escapes, anchors, character classes
+and at most one `.*` wildcard. Branching/nested repetition and unsupported patterns are rejected.
+Use the literal `strings search --contains` convenience when no regex is needed.
+
+Other pinned upstream operations explicitly return `scanPolicy.workBound: not-guaranteed`:
+their page/output limit may follow a full scan, and transport cancellation does not prove backend
+work stopped. The generic accepted result limit is 1 MiB. This policy is distinct from the actual
+work counters on facade-owned scans; narrow function/address/filter selectors for costly upstream
+analyses. Scores, similarities, estimated bounds, name suggestions and malware/IOC patterns carry
+`semantics` with their algorithm and limitations. Confidence labels are not calibrated probabilities.
+
+## Emulation
+
+Supported policies are little-endian `x86-cdecl` (32 bits), `windows-x64` and `sysv-x64`. `--abi auto`
+recognizes the supported compiler specifications, including Windows Clang. Unknown architectures
+or compiler policies are explicit errors. Inputs run in isolated emulator memory and cannot patch
+the program database.
+
+`emulation emulate-function --arguments '[2]' --registers '{}' --memory '[]'` supplies unsigned
+integer/pointer arguments using the ABI's register/stack layout. Explicit register inputs can
+override argument registers; PC/SP remain ABI-owned. Initial memory accepts at most 64 regions
+and 64 KiB in total. The ABI creates an aligned stack, correctly sized return address and Windows
+shadow space. Floating-point/aggregate ABI lowering, OS services and imported process behavior
+are not modeled by this helper.
+
+Read `completed`, `hit_return`, `stop_reason`, `steps_executed`, `abi` and `pointer_bytes`.
+`completed: false` is not a function result. Budgets count instructions: at most 100000 steps per
+candidate and a 1–30 second timeout. Hash batches accept at most 256 candidates and 200000 total
+instructions; incomplete candidates cannot match a target hash. Batch `complete`, `truncated`
+and individual `outcomes` report the actual scope checked. This is independent from live debugging.
+
+## Memory and signature edits
+
+`memory create-block` accepts hex/base64 initial bytes, optional size/fill byte, uninitialized
+memory, overlay, volatile and comment inputs. Content determines omitted size; size is capped
+at 16 MiB. Uninitialized memory cannot carry initial bytes or nonzero fill. Overlays retain their
+distinct address-space identity. The saved database is independently checked for metadata and
+the entire initialized-content digest before acknowledgment. `functions set-function-prototype`
+also accepts `--calling-convention`; saved signature types and convention are verified.
+
+These remain complex private edits. Request IDs retrieve retained outcomes; lost responses are
+reconciled from saved effects, never blindly re-created. Publish with explicit merge on the
+unchanged shared base; structural divergence still retains a conflict.

package/skills/insight-ghidra/references/recovery.md

@@ -0,0 +1,53 @@
+# 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.

package/skills/insight-ghidra/references/research.md

@@ -0,0 +1,101 @@
+# Research with a private context
+
+See [query semantics and work limits](query-semantics.md) for completion/truncation, actual type
+resolution, qualified heuristics, supported emulation ABIs and memory/signature input variants.
+
+`ghidra save-all --session <id>` saves every Ghidra context in that session and reports a
+separate outcome for each input. It does not publish. A partial result preserves completed saves;
+repeating the same request ID retrieves those outcomes without another pass.
+
+`ghidra changes discard --session <id> --target <id>` explicitly removes that context's pending
+program edits, retains its former private snapshot and restores its own opening base. It requires
+Destructive permission. Other sessions and the shared revision remain unchanged; use explicit
+refresh to receive a newer shared base afterward. Close a live debugger before discarding static
+edits. The saved trace remains separate from the program's opening snapshot.
+
+Open input with `insight-cli ghidra open ./client.exe --session new --json`. Store the returned
+`session` and `target` as the explicit scope for every later research call. Names are display
+labels; equal filenames or addresses in different inputs do not select the same object.
+
+Use `ghidra strings search --contains config.json`, then `ghidra xrefs to --address <string>`.
+Reference results include a containing function address when available. Pass that address to
+`ghidra functions get` or `ghidra functions decompile`. Add the same session/target selectors and
+`--json` to each command; consult generated help for paging and exact flags.
+
+An exported object can also have an external-entry metadata reference. That item has
+`from: null`, `kind: "EXTERNAL"` and `source: "entry-point"`; it counts in the returned
+page but has no source address to navigate. Ordinary references retain their hexadecimal
+`from` address and containing function when available.
+
+Use `ghidra functions rename` and `ghidra comments set` for private edits. `--clear` (or empty
+text) represents a null/absent comment. Successful edits are checked by readback and saved before
+`applied`. A later read sees the local result; another session remains independent. These edits
+do not publish themselves. Use `ghidra merge` to publish the selected context explicitly.
+
+Another session retains its view until `ghidra refresh`. Refresh receives safe shared changes and
+preserves local work. An overlapping field retains original/local/shared values; merge publishes
+nothing while any conflict remains. Resolve that field with its ordinary setter,
+`--resolve-conflict --expect-shared <observed value>` (or `--expect-shared-null` for an absent
+comment). A later shared change invalidates the decision and preserves your work.
+
+Types, signatures and memory edits are saved as complete private program state. They publish
+when the shared base is unchanged. After divergence, unproved structural categories remain a
+conflict: retain the old session, open a new session on the current target, and transfer the desired
+work through ordinary operations. A script is not replayed as a merge algorithm.
+
+The editing groups include types/categories/layouts, labels/references, properties/bookmarks,
+memory flags, functions/variables/tags and batch comments/documentation. Factory's `Destructive`
+gate covers deletion and replacement operations separately from ordinary Update. These broader
+edits currently use complete saved-state publication; their grouping does not grant scalar merge
+semantics. Boolean fields use explicit values; the no-return setter calls its flag `--non-returning`
+to keep it distinct from CLI negation syntax.
+
+`ghidra scripts list` returns stable `installation:` and `context:` script IDs. Pass an exact ID to
+`ghidra scripts run --script-name <id>`, or source to `ghidra scripts run-inline --code <source>`.
+Script arguments follow the pinned whitespace-splitting convention. Execution output is returned
+with the saved private state. Script file/network/process effects are immediate and are not undone
+by program rollback or replayed by merge. An uncertain script remains unresolved even when some
+program changes can be observed.
+
+Additional read groups expose analysis, listings, types, documentation, memory, symbols and
+emulation through typed flags. `functions inspect`, `comments inspect`, `strings list` and
+`strings search-regex` cover broader selection than the convenient walkthrough commands.
+Boolean options take explicit `true`/`false`; complex inputs take bounded JSON. Result variants
+are under `value` with the same session/target identifiers. Generated help lists domain arguments;
+the caller supplies no program/instance routing. For P-code dataflow choose an actual operation
+address from `analysis get-function-pcode`; a function prologue may have no high P-code operation.
+
+For comparisons, keep `--session`/`--target` as the first side and provide `--other-target`.
+`--other-session` defaults to the first session; specify it to compare another agent's private
+context. `documentation compare`, `functions diff` and the fuzzy matching commands use these
+selectors. Fuzzy matching excludes candidates shorter than eight instructions. Results return
+both logical scopes and preserve the selected private views.
+
+`documentation transfer` instead selects the private receiver with `--session`/`--target` and the
+source with `--source-target` and optional `--source-session`. It copies documentation at matching
+addresses; it does not publish. Use `--dry-run` to preview counts. The operation requires
+Destructive because transferred definitions/annotations can replace existing receiver data.
+After an applied result, publish through ordinary `ghidra merge`. Retried request IDs retrieve
+their recorded outcome; recovery retains the source revision actually used by that request.
+
+Opening a second input in the same session preserves the first context. Different processes using
+the same session/target share one ordered context. Independent agents choose separate sessions.
+Calls return explicit scope so parallel outputs can be associated with the intended input.
+`sessions status <session> --limit <n> --offset <n>` pages saved contexts; `--target` selects one.
+Its `externalRequests` reports uncertain archive/session-save outcomes without conflating them
+with unpublished program edits. A truncated result indicates that another page may exist.
+
+`ghidra status` verifies the selected tool and reports saved pending work. `ghidra save` retains
+private changes without publishing. `ghidra close` saves and releases the owned process; continue
+with the same open selectors to retain local work. Save/close accept the optional request ID.
+
+The `ghidra ui` commands use the same explicit scope. `cursor --type all` reads address, function,
+selection and focused program; headless facets return null with an explicit reason. `tools` starts
+the owned GUI when needed and lists its tools using logical program scope. `goto --address <at>`
+navigates the owned browser and verifies the cursor. `prompt-policy --action enable --seconds <n>`
+temporarily handles the backend's known prompts in that owned GUI for 1–300 seconds; status and
+disable inspect or end the policy. Changing UI commands accept request IDs. These actions do not
+publish program work. Switching modes retains private edits and other sessions keep their views.
+
+Selected native SDK commands and their effect/budget contracts are described in
+[native workflows](native-workflows.md).

package/skills/insight-ghidra/references/setup.md

@@ -0,0 +1,50 @@
+# Setup
+
+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.

package/skills/insight-ilspy/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: insight-ilspy
+description: Recover C#, inspect IL/types/metadata, extract resources or export projects from managed .NET assemblies through insight-cli ILSpy. Choose native analysis for NativeAOT or ordinary PE machine code.
+---
+
+# Insight ILSpy 0.2.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
+CLI calls too. An explicit **no command was sent** denial is known undispatched and can be
+retried through that route. Keep HOME, profile and owner state; see
+[host execution permissions](references/agent-execution.md). A lost mutation reply needs
+request/status recovery, never blind retry.
+
+Use the project's preferred tool and evidence conventions. Use ILSpy for static managed
+assemblies with CLR metadata. It does not execute the assembly, recover C# from NativeAOT,
+or establish runtime behavior from pseudocode alone.
+
+1. `insight-cli ilspy status --json` checks the selected profile. If needed,
+   `insight-cli ilspy install` prepares the pinned ILSpy and private .NET runtime.
+   No machine-wide SDK is required. Use generated install help for local archives,
+   offline cache or an external executable; see [workflows](references/ilspy.md).
+2. Start with `ilspy query <input> --json` and `--view types`, then decompile one relevant type/member,
+   inspect its IL or metadata, or enumerate resources. Use returned target identity
+   across calls/tools. `--target` reuses immutable bytes without opening Ghidra.
+3. Text responses default to a 16000-character window. Page with `--limit-chars` and
+   `--offset-chars`; combine only pages with the same `textSha256`. The hash covers observed
+   native text, which may itself be incomplete. Save full bounded text with `--output`,
+   or extract a selected resource into new ordinary output paths.
+   Recover a full project only when the question calls for it. Distinguish recovered
+   code/names from source truth. Record commands/input identity alongside findings
+   according to project rules.
+4. `tools processes --tool ilspy --all` shows executions and retained diagnostics.
+   Inspect partial exports after failure; choose a new output path for an intentional
+   retry. Close only owned executions; uninstall preserves external files and research.
+
+Execution and preparation need Factory Update permission. `ilspy --help` supplies exact
+commands/options; the [workflow reference](references/ilspy.md) covers inputs, outputs,
+resource/project export and continuation. Save a completed project file/folder through
+`insight-cli artifacts save` when a checkpoint is useful; it is independent of Ghidra merge.
+
+Hash extracted resource bytes themselves; the resource-list text has a different digest
+and is not the extracted file. For a requested checkpoint, finish the notes/recovered files,
+save their chosen containing folder, and read back the returned saved path. Include that
+exact path in the final handoff; do not substitute the ordinary export path or an inferred UUID.