@eyeauras/insight-cli 0.2.0 → 0.2.1

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

@@ -0,0 +1,52 @@
+# 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
+Ghidra, Java, authentication, target/session selectors or evidence metadata. Relative input
+paths resolve against the caller's working directory. Use `--help` for generated syntax.
+
+Save existing project files in their existing format; no `notes.md`, `finding.md` or
+`research/` layout is required. The saved copy is a checkpoint and does not replace the
+project's canonical evidence location or its source-of-truth rules.
+
+Write notes and useful external-tool outputs as ordinary files while investigating. When
+the selected files are no longer being edited, save one file, a completed worker subfolder
+or the relevant project folder. For a project without a prescribed layout, for example:
+
+```sh
+insight-cli artifacts save ./research --json
+```
+
+The receipt has `state: "saved"`, `path`, `kind` (`file` or `directory`), `files`, `bytes`
+and `sha256`. `path` points to an ordinary browsable copy with the source basename and
+relative layout. Empty files and empty directories are retained. File count counts regular
+files; byte count counts their contents. A file's SHA-256 hashes its bytes; a directory's
+SHA-256 hashes its canonical manifest of relative paths, kinds, file lengths and hashes.
+The manifest is stored beside the content, outside the returned directory.
+
+Before claiming a verified checkpoint, read the expected files at the returned `path` using
+ordinary file tools. Preserve that path verbatim in the handoff, alongside the receipt;
+profile and snapshot identifiers must not be reconstructed from memory. If access is denied,
+retain the actual receipt and state that readback remains unverified.
+
+The service copies and syncs data before publishing the completed snapshot. Failure does
+not return a successful receipt or expose a partial completed snapshot. Source edits made
+after a successful save do not change the copy. Treat saved copies as retained snapshots;
+edit the original research folder and save a new copy for another checkpoint. Each call
+creates a new saved copy, including a repeated call after a lost response.
+
+Keep a directory stable for the save: detected concurrent edits are rejected. Copying
+several files is not an atomic filesystem snapshot of a directory that other agents keep
+changing. Symbolic links and special files are rejected rather than followed or silently
+omitted. Select the actual intended regular file/directory. Do not save a directory that
+contains the destination materials store. Traversal supports at most 100,000 entries and
+128 levels to bound inventory memory and recursion. Disk/permission failures return nonzero.
+
+The saved bytes establish what was retained. Commands, tool versions and interpretations
+written in a note remain the author's statements, not execution attestations. No upload,
+tool execution or Ghidra publication is performed by saving materials.
+
+Profile deletion/configuration invalidation is blocked while retained materials exist,
+as with retained research work. Close tool contexts normally; preserve snapshots separately
+if retiring a profile. There is no automatic registration, cleanup policy, graph database
+or additional read API: read the receipt's path with normal file tools.

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

@@ -0,0 +1,62 @@
+# Debug an input in its private context
+
+Use the same `--session` and `--target` as static research. `debugger launch-offers` lists
+available launchers and starts the owned GUI services when needed. `debugger launch` executes a
+verified copy of the selected immutable input in an owned run directory. It accepts `--offer`,
+`--args`, `--cwd`, a bounded launch timeout and the optional request ID. A second live process
+uses another session; it does not replace this context's current process.
+
+For local macOS `lldb`, `--stop-at-entry` launches stopped before normal program startup.
+The response verifies a live `STOPPED` target and reports `stoppedAtEntry: true`. This is
+useful for short programs: inspect/map/set breakpoints, then explicitly resume. Without the
+flag, the existing immediate-run behavior is unchanged. Other offers reject this flag before
+a CPU intent is reserved. An unknown stopped launch still requires ordinary request recovery.
+
+Read `debugger status`, `modules`, `registers`, `stack-trace` and `traces`. Address conversion
+uses `static-to-dynamic` and `dynamic-to-static`; memory and breakpoint commands take dynamic
+addresses. Lists are paged. Read results identify the logical context and current trace, and
+report whether the trace is connected or retained after disconnection. `--trace` selects a
+saved trace within this context; IDs from another context are rejected.
+
+Changing commands include interrupt, resume, step into/over/out and breakpoint set/remove.
+Their optional request ID retrieves the recorded result without executing again. A genuinely
+unknown CPU action remains uncertain; a later program counter alone does not prove how many
+instructions executed. Read-only observation remains available for uncertain debugger actions.
+Program merge does not roll back execution, debugger I/O or other process side effects.
+
+Trace databases are checkpointed separately from the private program and verified by independent
+packed-database readback before acknowledgment. Reopening after process replacement restores
+saved trace data as disconnected. It does not restart the debuggee or reconstruct CPU execution.
+Ordinary static program edits remain private and retain the usual merge/refresh behavior.
+Static breakpoint bookmarks created by debugger actions also count as pending program changes.
+They follow explicit merge/refresh and complex-change conflict rules; CPU execution does not
+wait for publication, and publishing a program never resumes another session's process.
+
+On macOS, launch enforces the selected working directory, including paths with spaces and
+quotes. A GUI backend crash ends the owned live debuggee through its debugger controller.
+Verified trace data retained before a lost action response is adopted on disconnected continuation,
+unless a later observation already saved a newer view. The CPU action itself remains uncertain.
+
+On macOS, use an installed local LLDB and an executable supported by that host. GUI startup
+prepares the Python wheels already supplied with Ghidra in owned storage; it does not install
+packages into system Python. A launcher's optional Python executable and Windows debugger
+directory are Factory profile settings. Native Windows/Linux acceptance remains deferred.
+
+Use generated help for exact flags. A retained static breakpoint bookmark may remain after its live trace placement is
+removed; `trace_location_count` distinguishes current placements from that static metadata.
+
+For a call observation, set the mapped function breakpoint **before** resuming from entry.
+After the stop, check the PC against that address, then capture arguments and stack before
+stepping. Step-out verifies return to the native caller in the same thread and stack;
+return registers are observed without being modified. A competing stop or unavailable caller
+does not count as a verified return. A requested step whose reply
+or observed completion is unknown remains journaled; do not issue another CPU action to
+try to recover a missing return. Retain its diagnostics and use request/status recovery.
+
+For another intentional run, close and reopen the same owned context first: this disconnects
+and retains the previous trace without relaunching it. Then launch with a distinct request ID
+and desired arguments. A connected debugger remains busy even after its subject has exited;
+selecting or reading its old trace is not a request to execute the subject again.
+Map the new process and explicitly set/check its live breakpoints before each resume from
+entry. Old static bookmarks do not establish new trace placements. Reopening restores each
+trace's saved snap/thread, including inactive traces; choose its returned ID with `--trace`.

package/skill-bundle/insight-ghidra/references/extensions-and-sync.md

@@ -0,0 +1,124 @@
+# Managed extensions and synchronization
+
+`insight-cli` keeps targets/sessions above tools. Both features below belong to the Ghidra
+context/runtime selected by the existing profile; they introduce no new agent/session objects.
+The Factory API uses the same command paths and options as these CLI examples.
+
+## Consume a ready-built SDK extension
+
+Use an unpacked standard Ghidra 12.1.2 extension module, with `Module.manifest` and
+`extension.properties` at its root. Directory basename and property `name` must agree.
+The module can contain compiled `lib/*.jar`, `data/languages` (including compiled Sleigh `.sla`,
+`.ldefs`, `.pspec`, `.cspec`) and `ghidra_scripts`. Build the extension with its own upstream
+SDK build before consumption. ZIP acquisition/extraction, dependency resolution, building a
+third-party extension and publishing extensions are outside this local management contract.
+
+```sh
+insight-cli ghidra extensions inspect --directory ./MyExtension --json
+insight-cli ghidra extensions install --directory ./MyExtension --sha256 <content-sha256> --json
+insight-cli ghidra extensions list --json
+```
+
+Inspect computes the content identity without executing extension code. Install requires the
+`Destructive` permission, consumes all regular files into profile storage and verifies the
+copy. It never edits the installed SDK or depends on the original directory after consumption.
+The identity covers sorted relative paths, SHA256 and size for every file; it is not a ZIP hash.
+Symlinks/special files, hidden/traversing paths and incompatible version metadata reject.
+Limits: 32 modules/profile, 8192 files and 256 MiB/module, 16 path components.
+A name stays pinned to one content identity; different builds use different module names or profiles.
+
+```sh
+insight-cli ghidra extensions disable --name MyExtension --json
+insight-cli ghidra extensions enable --name MyExtension --json
+```
+
+Stop the Factory IPC owner after changing the enabled set, then run the next ordinary command.
+A running owner refuses changed runtime configuration. Immutable module copies remain retained
+when disabled, so saved contexts can resume with their original language/type dependencies after
+re-enabling. Existing private work and unknown request/publication journals are preserved.
+Disabling the language required by a saved program does not convert that program to another language.
+Enablement/install are desired-state/content operations; repeating the same input is idempotent.
+No automatic extension updates or network/package-manager installation occur.
+
+Discover what the installed SDK actually provides:
+
+```sh
+insight-cli ghidra extensions capabilities --kind languages --filter MyProcessor --json
+insight-cli ghidra extensions capabilities --kind analyzers --filter MyExtension --json
+insight-cli ghidra extensions capabilities --kind plugins --filter MyExtension --json
+```
+
+These paged inventories return actual native IDs (and compiler IDs for languages); `managed`
+on analyzer/plugin classes identifies consumed modules. Select a language/compiler using
+`ghidra open --language <id> --compiler-spec <id>`. Use `analysis configure-analyzer --name <name>
+--enabled true` and `analysis reanalyze` in an explicit context. Program writes remain complex
+private changes and follow the existing saved-state verification/merge rules.
+Extension scripts have explicit inventory IDs such as `extension:MyExtension/Example.java`;
+run that ID through `scripts run`, never guess a process-global search path.
+
+For a GUI plugin, use `ghidra plugins set --plugin <class-id> --enabled true|false` with
+`--session` and `--target`. `plugins list` returns enabled managed plugins in that owned GUI tool.
+Only classes from enabled managed modules can be toggled. Enablement is read back immediately;
+its lifetime is the current GUI tool, rather than a promise to resurrect it after a crash.
+Plugin constructors/disposal may change program state: the operation saves a private snapshot
+and conservatively records a complex change. An uncertain effect is never replayed; close the
+owned context when its live effect cannot be established. Configuration dialogs, arbitrary
+plugin-specific option schemas, native libraries with platform installers and hot class unloading
+are not promised by this module contract; the explicit script API remains available.
+
+Extension code runs with the OS privileges of the owned JVM. Digest pinning establishes which
+code runs, not a security sandbox or a guarantee of third-party compatibility. Workers, GUI,
+inspection and publication helpers use the same verified enabled set. The storage-only local
+Ghidra Server continues to use the pinned base SDK and does not run managed analysis plugins.
+
+## Optional synchronization for one context
+
+The default remains explicit `merge` and `refresh`. Reads keep the private view. Configure an
+existing `(session, target, ghidra)` context explicitly:
+
+```sh
+insight-cli ghidra sync-policy get --session s_a --target t_exe --json
+insight-cli ghidra sync-policy set --session s_a --target t_exe \
+  --publish after-edit --refresh before-edit --json
+```
+
+| Setting | Behavior |
+| --- | --- |
+| `--publish manual` | Local edits and saves do not publish automatically. |
+| `--publish after-edit` | After a supported program edit has a verified saved acknowledgment, merge all pending work in that context. Also publishes pending work on explicit `ghidra save`. |
+| `--publish after-save` | Ordinary edits stay private; explicit scoped `ghidra save` merges all pending work after saving. |
+| `--refresh manual` | No automatic incoming update. |
+| `--refresh before-edit` | Refresh before a program-edit command; any returned conflict stops that edit before dispatch. Safe incoming changes from the refresh remain retained. |
+
+Supported program-edit commands include ordinary names/comments, types, bytes/assembly,
+analysis and scripts. Policy excludes control commands (`open`, `close`, `merge`, `refresh`,
+policy/discard), cross-target transfer, GUI/debugger, archive/project/server operations, file
+exports, library databases and Version Tracking. Session-wide `save-all` saves privately;
+use scoped `save` for automatic publication. Read-only queries never trigger refresh/publication.
+Automatic refresh/publication also requires the current Factory `Update` permission, including
+when the edit itself is gated by `Destructive`. Revocation prevents starting those automatic
+effects; retrieval of a completed workflow does not repeat them. No background timers, watchers
+or automatic semantic conflict resolution are introduced.
+
+A successful automatic edit includes its normal local result plus `automatic.refresh` and/or
+`automatic.publication`, final `pendingChanges` and `sharedState`. After a publication conflict,
+the command fails with `state: conflict`, `localApplied: true` and the retained `local` result.
+Nothing from that merge is published. An incoming conflict reports `phase: refresh` and
+`localApplied: false`; the requested edit was not started. Lost local replies may report
+`localOutcome: unknown`; they do not falsely assert that the local effect failed.
+
+Automatic merge uses exactly the manual contract: any conflict prevents the whole publication;
+only verified scalar categories combine after divergence; complex divergence retains both
+versions. Use explicit refresh, inspect/resolve scalar conflicts, or transfer complex changes
+onto a current base. A failed automatic workflow does not silently retry after resolution;
+use a new request or explicit merge for the new intention.
+
+Policy survives owner replacement. Optional request IDs (up to 128 characters) bind the local edit, incoming refresh and publication workflow. Repeating the same ID/input
+retrieves its result or reconciles the original publication; it never replays a check-in or
+uncertain script. The original workflow keeps its original policy even if policy changes later.
+Retrying an earlier manual edit does not retroactively publish it after enabling automatic mode.
+Without a request ID, a call is a new intention, as elsewhere in the facade.
+
+The caller ID reserves the complete automatic workflow in the common profile namespace, even
+when incoming conflicts prevent the local command from starting. It cannot be reused by an
+explicit merge, close, export or administration operation. Internal child effects have derived IDs.

package/skill-bundle/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/skill-bundle/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/skill-bundle/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.