@eyeauras/insight-cli 0.1.0 → 0.2.1

package/skill-bundle/insight-dnspy/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

package/skill-bundle/insight-dotnet-dump/SKILL.md

@@ -0,0 +1,46 @@
+---
+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.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.
+
+Start with `insight-cli dotnet-dump collect --pid PID --output research/worker.dmp`.
+The default Heap dump includes managed objects; Mini may lack required heap data. Collection
+has a deadline and accepts only a nonempty file below 4 GiB. It does not execute dump data.
+
+Use `analyze FILE --command clrthreads` or `--command clrstack` for thread context, then
+`--command 'dumpheap -type TYPE'` to locate objects and `--command 'dumpobj ADDRESS'` for
+fields. Reuse the returned `--target ID` instead of a file. `gcroot ADDRESS` can investigate
+retention. Interpret the actual output: an empty type selection, unavailable DAC or SOS error
+is not evidence that the requested object was found. Addresses belong to that dump only.
+Use `--command 'help dumpheap'` for native SOS query syntax.
+The API accepts one supported inspection command; it does not expose arbitrary debugger
+scripts, chaining, symbol-server configuration or execution. Keep static object snapshots
+separate from claims about current live state.
+
+Use the existing project RE instructions and evidence format. `status` checks readiness;
+`install` prepares the pinned tool and private .NET 10.0.13 from our GitHub Releases.
+`--archive`, `--dotnet-archive` and `--offline` support local preparation; `--executable`
+selects a compatible external tool, whose runtime/dependency closure remains user-managed.
+Managed admission is macOS ARM64. A native compatible runtime/DAC is required for dump
+inspection; a Windows dump is not promised readable on macOS.
+
+Live commands require an explicit `--pid`. The selected process remains external: the CLI
+owns its collector, not that target's lifetime. Use the PID supplied for this investigation;
+process birth is checked around collection, with the reported OS identity strength. If the
+process uses a custom TMPDIR, pass `--diagnostic-directory` with that directory. Do not
+infer target ownership from a successful attachment or stop another agent's process.
+
+Text views page with `--limit`/`--offset`; `--output FILE` retains complete bounded text in
+a new ordinary file. Native text has a 4-MiB output bound; an output-limit error is not a
+complete inventory. Save finished project files/folders with `artifacts save` when useful.
+`tools processes --tool dotnet-dump --all` and `show ID` retain collector diagnostics. Update
+permission is required. Generated `--help` owns exact syntax. Uninstall preserves research.

package/skill-bundle/insight-dotnet-dump/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

package/skill-bundle/insight-dotnet-stack/SKILL.md

@@ -0,0 +1,39 @@
+---
+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.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 `insight-cli dotnet-stack report --pid PID` for a lightweight live stack snapshot.
+Inspect the managed callers around native wait/sleep frames: a wait identifies where a
+thread was sampled, not by itself why an application is stalled. Keep PID/birth, capture
+time and relevant frame names in the project evidence. Different snapshots may legitimately
+differ. Use dotnet-dump for object/field questions and dotnet-trace for a bounded view over
+time instead of presenting one stack snapshot as a performance measurement.
+
+Use the existing project RE instructions and evidence format. `status` checks readiness;
+`install` prepares the pinned tool and private .NET 10.0.13 from our GitHub Releases.
+`--archive`, `--dotnet-archive` and `--offline` support local preparation; `--executable`
+selects a compatible external tool, whose runtime/dependency closure remains user-managed.
+Managed admission is macOS ARM64. A native compatible runtime/DAC is required for dump
+inspection; a Windows dump is not promised readable on macOS.
+
+Live commands require an explicit `--pid`. The selected process remains external: the CLI
+owns its collector, not that target's lifetime. Use the PID supplied for this investigation;
+process birth is checked around collection, with the reported OS identity strength. If the
+process uses a custom TMPDIR, pass `--diagnostic-directory` with that directory. Do not
+infer target ownership from a successful attachment or stop another agent's process.
+
+Text views page with `--limit`/`--offset`; `--output FILE` retains complete bounded text in
+a new ordinary file. Native text has a 4-MiB output bound; an output-limit error is not a
+complete inventory. Save finished project files/folders with `artifacts save` when useful.
+`tools processes --tool dotnet-stack --all` and `show ID` retain collector diagnostics. Update
+permission is required. Generated `--help` owns exact syntax. Uninstall preserves research.

package/skill-bundle/insight-dotnet-stack/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

package/skill-bundle/insight-dotnet-trace/SKILL.md

@@ -0,0 +1,45 @@
+---
+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.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 `insight-cli dotnet-trace collect --pid PID --duration-seconds 5 --output research/worker.nettrace`.
+The default `dotnet-sampled-thread-time` profile measures sampled thread wall-clock time.
+A sleeping method can rank at 100% while consuming little CPU. This API does not use the
+Linux-only `cpu-sampling` kernel profile. Other declared EventPipe profiles cover common
+runtime or GC events; a trace without sample events need not have a useful method ranking.
+
+Use `report FILE --count 10` for inclusive method ranking (`--exclusive` changes the metric).
+Reuse `--target ID` for captured immutable bytes. `convert FILE --format Speedscope --output
+research/worker.speedscope.json` creates a new ordinary JSON export; Chromium is also supported.
+Preserve the original trace, profile, duration, target identity and collection conditions.
+Limited/dropped samples and startup/rundown overhead constrain inference; do not call this a
+CPU speedup benchmark merely because a report contains percentages.
+
+Use the existing project RE instructions and evidence format. `status` checks readiness;
+`install` prepares the pinned tool and private .NET 10.0.13 from our GitHub Releases.
+`--archive`, `--dotnet-archive` and `--offline` support local preparation; `--executable`
+selects a compatible external tool, whose runtime/dependency closure remains user-managed.
+Managed admission is macOS ARM64. A native compatible runtime/DAC is required for dump
+inspection; a Windows dump is not promised readable on macOS.
+
+Live commands require an explicit `--pid`. The selected process remains external: the CLI
+owns its collector, not that target's lifetime. Use the PID supplied for this investigation;
+process birth is checked around collection, with the reported OS identity strength. If the
+process uses a custom TMPDIR, pass `--diagnostic-directory` with that directory. Do not
+infer target ownership from a successful attachment or stop another agent's process.
+
+Text views page with `--limit`/`--offset`; `--output FILE` retains complete bounded text in
+a new ordinary file. Native text has a 4-MiB output bound; an output-limit error is not a
+complete inventory. Save finished project files/folders with `artifacts save` when useful.
+`tools processes --tool dotnet-trace --all` and `show ID` retain collector diagnostics. Update
+permission is required. Generated `--help` owns exact syntax. Uninstall preserves research.

package/skill-bundle/insight-dotnet-trace/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

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

@@ -0,0 +1,67 @@
+---
+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.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.
+
+Follow existing project RE and evidence conventions. Frida instruments a running process;
+choose an explicitly authorized PID. This facade owns the collector, while the target stays
+with its original owner. Stopping the collector never signals that target.
+
+1. `insight-cli frida status --json` checks readiness. `frida install` obtains our pinned
+   Frida Node 17.24.0 bundle from GitHub Releases, including its NAPI-v8 binding, JavaScript
+   dependencies and full notices. It uses the CLI's Node runtime; Python is unnecessary.
+   Managed delivery requires macOS 14+ ARM64. `download`, `install --archive FILE --offline`,
+   `doctor` and `uninstall` use the shared lifecycle. An external compatible Node bundle can
+   be selected with `install --executable /path/to/frida/build/src/frida.js`; adjacent binding
+   and resolved runtime dependency families are fingerprinted and never deleted.
+2. `frida modules --pid PID --json` establishes runtime module names and load addresses.
+   `frida exports --pid PID --module NAME --json` narrows to one module. `--limit`/`--offset`
+   page records. Runtime pointers differ from static addresses under ASLR; establish module
+   and image correspondence before combining findings from Ghidra/LLVM with live evidence.
+3. Write a focused ordinary JavaScript file using the [Frida JavaScript API](https://frida.re/docs/javascript-api/).
+   For a known integer-valued exported function, an observation hook can be:
+
+   ```javascript
+   const at = Process.mainModule.getExportByName('quote_total');
+   Interceptor.attach(at, {
+     onEnter(args) { this.count = args[0].toInt32(); },
+     onLeave(value) { send({count: this.count, result: value.toInt32()}); }
+   });
+   ```
+
+   Match argument types, calling convention and module to the actual program. This example
+   is not a generic signature for every function. `frida observe --pid PID --script FILE
+   --duration-seconds 2 --output research/calls.json --json` captures the source bytes, loads
+   it, collects messages, requests unload and detaches. The output records the source hash,
+   runtime version, original PID/birth, native diagnostics and cleanup acknowledgment.
+4. Inspect `complete`, `state`, script errors and cleanup fields. Script errors or early
+   target detach produce partial evidence. No observed call does not prove absence. Ordinary
+   `send`/console/error messages and optional binary payloads are retained. `--limit`/`--offset`
+   page event messages; `--output` saves the full bounded envelope to a new ordinary file and
+   creates parents. Use `artifacts save` for a checkpoint when useful.
+   Both the response and saved envelope include `summary`: total protocol events and counts
+   of script send/error/log messages. A send message is not universally a call. Derive call
+   counts from the retained payload type selected by your hook; do not count runtime,
+   loaded or completed receipts as calls or estimate counts by reading a long event list.
+5. The observation window is 1–120 seconds; collector execution has a separate finite deadline
+   that survives owner loss. Native SDK helpers have their own inherited deadlines; status
+   remains `native_children_pending` and uninstall is blocked until they exit. Native output is bounded to 4 MiB and 10000 messages. Arbitrary
+   script patches or application side effects are not automatically rolled back by unload.
+   Avoid unnecessarily broad hooks and large payloads. `tools processes --tool frida --all`
+   shows owned collector history. A recovered live macOS PID may be unverified: wait for the
+   deadline and inspect retained evidence instead of replaying an injection blindly.
+
+The pinned backend has a known attach failure on a bare C process without CoreFoundation;
+our native probe reproduces it explicitly. A process already loading CoreFoundation worked.
+Report the failure and choose a suitable debugger/fixture; do not silently load frameworks
+into an unrelated process. macOS authorization/hardened targets can also prevent attach.
+An imported PE is not a runnable local macOS process. Generated help owns exact syntax.

package/skill-bundle/insight-frida/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

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

@@ -0,0 +1,91 @@
+---
+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.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.
+
+Ghidra operations can exceed the host execution tool's first wait. If it returns a running
+session/cell ID, await that same execution with the host's wait/poll facility until terminal
+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.
+
+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
+`kill` explicitly interrupts verified owned work and preserves its journals.
+For archives, external launchers, server lifecycle or removal, read [managed runtime](references/managed-runtime.md).
+
+This skill and its executable helper are one npm package. Run `insight-cli skill insight-ghidra` to locate
+these installed resources. Use generated `--help` for syntax; read the references as needed.
+Follow applicable project RE rules for tools, source of truth, evidence layout and format;
+this package's walkthroughs fill gaps rather than replacing those conventions.
+
+For coordinating a reverse-engineering investigation with ordinary files, external tools
+and multiple agents, locate the RE workflow with `insight-cli skill insight-re`. When a retained checkpoint is useful, save
+a completed project file or folder with
+`insight-cli artifacts save <path>`; [save semantics](references/artifacts.md) describe the
+ordinary saved copy and its receipt. Neither operation requires a Ghidra installation.
+
+1. Select the configured runtime profile. Ordinary work uses a managed local server; an external
+   server is optional. See [setup](references/setup.md). Factory permissions authorize changes.
+2. Open the input with `ghidra open <input> --session new --json`. Retain the returned session and target.
+   Another agent chooses `new` independently; one session can open several inputs.
+3. Pass both `--session` and `--target` on research calls. Follow strings to xrefs and their
+   function addresses, then inspect/decompile. Decompilation defaults to a 16000-character
+   window; page with `--limit-chars`/`--offset-chars` and retain `textSha256`. Native
+   truncation remains explicit even at the end of the observed text. See [research](references/research.md).
+4. Rename functions or set/clear comments through ordinary commands. An `applied` result means
+   verified saved private work. Other sessions keep their own views; local edits remain unpublished in the default manual mode.
+5. By default, publish explicitly with `ghidra merge`; receive safe shared changes with `ghidra refresh`.
+   Resolve overlapping names/comments against an explicitly observed shared value. A conflict
+   prevents the whole selected merge and retains local work.
+6. Continue with `ghidra open --session <id> --target <id>`. For uncertain outcomes inspect
+   `sessions status <id> --target <id>` and [recovery](references/recovery.md). Supplying a stable
+   optional `--request-id` lets a repeated changing intent retrieve its outcome without rerunning.
+7. Finish by closing each context you own with scoped `ghidra close`, preserving private work.
+   If this profile's local server belongs exclusively to your investigation and all its contexts
+   are closed, use `ghidra server stop`, then verify `ghidra status` has no remaining processes.
+   `ipc-server stop` stops the CLI owner; it does **not** stop Ghidra's local server. Stop that
+   owner last when needed. For a shared profile/server, leave server shutdown to its coordinator;
+   an individual worker closes only its own contexts and never kills unrelated processes.
+
+The facade exposes the pinned static research/editing catalog, merge/refresh, project/server/GUI
+controls, debugger, archive exchange and supported recovery. Preserve private work
+and journals while an outcome is unresolved. The CLI supplies the investigation tools; agents
+choose research goals and interpret findings.
+Installing this package does not register this skill in an agent's configuration.
+
+For project files, program export/import and configured-server administration, read
+[administration](references/administration.md). These operations preserve separate research views;
+their external effects do not participate in program merge.
+
+For owned GUI execution, CPU state, breakpoints and retained traces, read
+[debugger](references/debugger.md). Execution side effects remain separate from program publication.
+
+For explicit external documentation exchange and retained submission outcomes, read
+[archive](references/archive.md).
+
+For selected native SDK extensions (VT, DB differences, byte/assembly edits, formats, GDT,
+FID/BSim, namespaces and typed IR), read [native workflows](references/native-workflows.md).
+
+For managed SDK extension modules, actual language/analyzer/plugin discovery and opt-in
+automatic synchronization, read [extensions and sync](references/extensions-and-sync.md).
+
+For authorized macOS local debugging, use `ghidra debugger launch --stop-at-entry`
+with the returned session/target and `--json`; then inspect status, registers and stack
+before resuming. The default launch runs immediately, so a short program may exit before
+an interrupt. Before resuming from entry, map the selected function and set a live breakpoint at the
+returned dynamic address. Resuming a short program without that breakpoint can run it to
+exit before any call is observed. At the breakpoint verify PC, then read arguments/stack
+and step out or over the call to inspect its actual return.
+Repeat mapping and live breakpoint setup for every new launch. A saved breakpoint bookmark
+does not prove placement in that new process; check its `trace_location_count` before resuming.
+Use `new` only when creating a session; subsequent calls take its actual returned ID.

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

@@ -0,0 +1,34 @@
+# Projects, files and server administration
+
+Research uses root session/target scope. `ghidra projects` manages separate projects inside the
+selected profile; these projects do not select or replace an agent's private context. Use an
+explicit `--project` for create/open/close/info/files and file operations. Closing releases the
+native handle and preserves files; deletion requires Destructive. File listings are paged.
+Moves select a source `--path` and an existing `--destination` folder. Existing names are preserved.
+
+`ghidra program export --session <id> --target <id> --output <file>` saves the selected private
+program as GZF without publishing. `ghidra program import --project <name> --input <gzf>
+--path /folder/program` adds that saved program to a managed project. Importing files does not
+change the immutable target's input identity. Export requires a new output file.
+
+`ghidra projects archive --project <name> --output <gar>` exports a native Ghidra project archive.
+`ghidra projects restore --project <new-name> --input <gar>` restores into a new independent owned
+project. Archive entries cannot escape their destination; restoration accepts at most 100,000
+entries and 4 GiB of declared uncompressed data. Research contexts and pending work remain separate.
+
+Changing operations accept `--request-id`. A verified native completion journal can recover a
+lost project response without executing that operation again. If no complete journal exists,
+changing that project stays blocked; read-only inspection remains available. Partial or different
+export output does not prove success and is preserved. Retain receipts for continuation.
+
+`ghidra server` operates on the configured local or external server. `status` reports connection
+state, including a missing runtime before installation; `start/stop` manage the owned local
+server (stop requires closed contexts). `connect` enables shared operations; `disconnect` releases the owned local server or the
+external connection. Reconnect preserves repositories. Repository/file/history/checkout commands
+require the explicit repository and relevant path. Admin actions require actual server authority
+alongside Factory permissions. Changing ACLs preserves other users and anonymous access.
+Facade reader/publisher authority and canonical publication checkouts remain protected.
+
+Unknown server administration outcomes are retained without blind replay. Server/file effects
+are independent of program merge. Use generated help for flags and Factory profile/secret commands
+for connection configuration.

package/skill-bundle/insight-ghidra/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

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

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