The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
docs: one house style, consistent structure, no em dashes
Claude94480e7efbde
diff --git a/docs/architecture/architecture.mdx b/docs/architecture/architecture.mdxindex fca26fba..9f198e0e 100644--- a/docs/architecture/architecture.mdx+++ b/docs/architecture/architecture.mdx@@ -11,7 +11,7 @@ The endpoint architecture is local-first: local endpoint telemetry can be inspec<img src="/images/beacon-architecture.png" alt="Beacon endpoint architecture showing agent harnesses sending local OTLP or hook telemetry into Beacon collection and normalization, then writing endpoint JSONL for local dashboard, Wazuh, Elastic, Datadog, Sumo Logic, Rapid7 InsightIDR, Microsoft Sentinel, AWS S3, Google Cloud Storage, optional Splunk HEC and Falcon LogScale HEC export, and customer-managed forwarding." />-## Endpoint Architecture+## Endpoint architecture1. **Runtime surfaces:** Supported [agent harnesses](/runtimes) expose different [telemetry surfaces](/concepts/core-concepts#runtime-surface). Beacon uses the strongest surface available for each runtime instead of forcing every tool through one adapter.2. **Local collection:** Beacon receives OTLP gRPC, OTLP HTTP, or native hook payloads on the endpoint, depending on the runtime.@@ -19,7 +19,7 @@ The endpoint architecture is local-first: local endpoint telemetry can be inspec4. **Local storage and inspection:** Beacon writes one JSON object per line to the [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log). The local [dashboard](/concepts/core-concepts#dashboard) reads recent runtime logs over a loopback-only service for rollout validation and investigation.5. **Forwarding:** External SIEM, log, and storage destinations consume the same normalized JSONL stream through [customer-managed forwarding](/concepts/core-concepts#customer-managed-forwarding), or receive events directly from optional collector exporters.-## End-to-End Flow+## End-to-end flow1. A supported runtime emits activity through OTLP or hooks.2. Beacon receives the signal locally and attaches endpoint and harness context.@@ -34,7 +34,7 @@ For CI and cloud-agent setup paths, see the [runtime surface overview](/runtimesupload compressed per-run snapshots directly to customer-managed GCS or S3without the persistent endpoint collector or Vector.-## Architecture Details+## Architecture detailsBeacon writes an OpenTelemetry Collector configuration with localhost receivers:diff --git a/docs/architecture/managed-architecture.mdx b/docs/architecture/managed-architecture.mdxindex 2c740c6a..3d3daaeb 100644--- a/docs/architecture/managed-architecture.mdx+++ b/docs/architecture/managed-architecture.mdx@@ -11,7 +11,7 @@ Use this architecture when agent activity needs to be visible across teams, endp<img src="/images/asymptote-platform-diagram.png" alt="Asymptote platform architecture showing agent activity flowing into managed visibility, policy, and investigation workflows." />-## System Architecture+## System architecture1. **Agent activity sources:** Endpoint agent harnesses, cloud-hosted agent applications, services, workers, serverless functions, and other execution environments produce runtime telemetry.2. **Collection paths:** Agent Beacon collects local endpoint activity, while the Asymptote Observe SDK instruments cloud-hosted agent applications.@@ -19,7 +19,7 @@ Use this architecture when agent activity needs to be visible across teams, endp4. **Governance layer:** Policy controls, identity mapping, approvals, SSO, RBAC, and audit trails connect runtime activity to users, teams, and security workflows.5. **Investigation workflows:** Timelines and case workflows organize prompts, tool calls, file access, command execution, and related context for review.-## Managed Capabilities+## Managed capabilities| Capability | Purpose || --- | --- |diff --git a/docs/architecture/system-architecture.mdx b/docs/architecture/system-architecture.mdxindex 5cca6d31..3228a55d 100644--- a/docs/architecture/system-architecture.mdx+++ b/docs/architecture/system-architecture.mdx@@ -14,7 +14,7 @@ Asymptote supports two architecture paths: the open-source [Agent Beacon](/conce</Card></Columns>-## Choose An Architecture+## Choose an architecture| Architecture | Use when || --- | --- |diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdxindex 703cdd34..7778bf22 100644--- a/docs/changelog/cli.mdx+++ b/docs/changelog/cli.mdx@@ -11,14 +11,36 @@ Stay up to date with the latest changes to the Agent Beacon CLI.## August 2026+### Documentation · August 23, 2026++- **One house style across the docs** · Rewrote the pages that had drifted into+ design-note prose so each one leads with what to run and what it does. The+ Qwen Code, Pi, Cline, OpenCode, and cloud-agent runtime pages, the macOS,+ Linux, and Windows install pages, and the sandbox contributor guide are+ shorter and read the same way as the rest.+- **Consistent headings** · Section headings are sentence case throughout, with+ product names left alone. Runtime pages now follow one section order, and the+ cloud-agent pages use `Overview` then `How it works` instead of two sections+ both called some form of overview.+- **Simpler punctuation** · Removed em dashes across every page in favor of+ plain sentences, colons, and lists.+- **Navigation gaps closed** · The Common Issues page is reachable from the+ sidebar, the local-scan and scan-gate pages are grouped under `beacon scan`,+ and the local inventory guide is listed with the other guides. Four broken+ in-page anchors now resolve.+- **Corrected runtime facts** · The runtime support matrix reported Pi's managed+ extension as unshipped; it now lists the telemetry Pi actually collects. The+ matrix also links the Windows package alongside macOS and Linux, and the+ endpoint path reference lists Pi's extension paths.+### v1.2.3 · August 22, 2026- **Cline is a supported runtime** · `beacon endpoint hooks install --harnesscline` installs a Beacon-managed plugin at `~/.cline/plugins/beacon.ts` thatcollects prompts, task lifecycle and errors, tool lifecycle and results,commands with exit codes, file reads and edits with diffs, MCP activity, and- per-task token usage and cost. Cline is not one runtime — the same agent core- runs as a VS Code extension, a JetBrains plugin, and a CLI — and one plugin+ per-task token usage and cost. Cline is not one runtime: the same agent core+ runs as a VS Code extension, a JetBrains plugin, and a CLI. One plugininstall covers every host on the machine, because Cline auto-discovers pluginfiles rather than requiring a registry command. Cline's own OpenTelemetryexport and hosted prompt storage are neither configured nor required.@@ -55,7 +77,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.collector config and a package upgrade has replaced the collector binaryunderneath the running process. Installing over an older version left theprevious collector serving OTLP from a deleted inode, ignoring the new config,- with ports answering and status reporting healthy — until reboot. The same path+ with ports answering and status reporting healthy, until reboot. The same pathmade `endpoint install --splunk-hec-endpoint ...` write a destination thatnever took effect. Install now restarts a service it finds running. This wasnot Linux-only; it affected the macOS `.pkg` upgrade path identically.@@ -64,8 +86,8 @@ Stay up to date with the latest changes to the Agent Beacon CLI.reported that the service, config, and managed files were removed and exited 0while the unit stayed enabled and the collector returned at the next reboot.Uninstall now refuses without privileges up front, collects errors from every- step rather than stopping at the first, and removes rotated log archives —- deleting only `runtime.jsonl` left up to 50 MB of retained prompt text and+ step rather than stopping at the first, and removes rotated log archives.+ Deleting only `runtime.jsonl` left up to 50 MB of retained prompt text andcommand lines behind, invisibly, because the file an operator would check wasthe one that had gone.- **Hook writes are no longer lost silently under a restrictive umask** · The log@@ -79,8 +101,8 @@ Stay up to date with the latest changes to the Agent Beacon CLI.write the log and whether the directory can be entered at all.- **MCP detection works on the OpenTelemetry path** · The`external-mcp-tool-call` and `secret-read-then-external-mcp` rules gate on- `mcp.server`, and on Claude Code — which reports through the collector rather- than through hooks — that field was always empty, so neither rule ever fired. A+ `mcp.server`, and on Claude Code, which reports through the collector rather+ than through hooks, that field was always empty, so neither rule ever fired. Apoisoned MCP tool reading a credential and handing it off scanned as acredential read with no exfiltration. The hook path already split`mcp__<server>__<tool>` into `mcp.server` and `mcp.tool`; the collector path@@ -96,7 +118,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.unchanged.- **Linear delete-path matching in the OpenCode plugin** · The plugin'sdelete-command pattern could backtrack polynomially on a command string- containing a separator followed by many newlines — and that string is whatever+ containing a separator followed by many newlines, and that string is whateverthe agent chose to run. Commands are now split on `&&`, `||`, `;`, and newlinesfirst, then matched once per segment with an anchored pattern. Same extractedpaths, plus a delete command with leading whitespace at the start of the string@@ -123,8 +145,8 @@ Stay up to date with the latest changes to the Agent Beacon CLI.migrated.- **Linux deployment profile** · A one-page reference for reviewing Beacon beforedeploying it: what it needs from the kernel, and what it costs to leave- running, with the command that verifies each claim. Its lead claim — statically- linked, no glibc version floor — is now enforced rather than assumed. A native+ running, with the command that verifies each claim. Its lead claim, statically+ linked with no glibc version floor, is now enforced rather than assumed. A nativeLinux build defaults cgo on, so the same `make` target produced a static binarywhen cross-compiled from macOS and a dynamic one when built on Linux, adifference invisible on the build host and fatal on a stripped or older one.@@ -142,7 +164,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.- **Beacon configures the right person on directory-backed hosts** · On a machinewhose developer accounts come from OpenLDAP, SSSD, or Active Directory ratherthan `/etc/passwd`, a system-mode install reported success, started a healthy- collector, and captured nothing — for every user, on every machine. Beacon is+ collector, and captured nothing, for every user on every machine. Beacon isbuilt without cgo, which is what makes its binaries statically linked with noglibc version floor, and the same setting made Go's account lookup read`/etc/passwd` directly without consulting NSS. Account resolution now falls back@@ -150,13 +172,13 @@ Stay up to date with the latest changes to the Agent Beacon CLI.Only system-mode installs were affected; a user-mode install configures your ownhome directory and never looked anyone up by name.- **`beacon` is on `PATH` after a package install** · The `.deb` and `.rpm`- installed to `/opt/beacon/bin` and linked nothing, so every documented command —- including the one the package's own postinstall prints — failed with+ installed to `/opt/beacon/bin` and linked nothing, so every documented command,+ including the one the package's own postinstall prints, failed with`command not found`. Both packages now provide `/usr/bin/beacon` and`/usr/bin/beacon-hooks`.- **One session, one harness name** · Hook events recorded the raw runtime namewhile OpenTelemetry events recorded the canonical one, so a single Claude Code- session appeared as both `claude` and `claude_code` — splitting it for any query,+ session appeared as both `claude` and `claude_code`, splitting it for any query,dashboard, or SIEM detection grouping by `harness.name`. Hook events now carry thecanonical name. If you have saved queries matching `claude`, `codex`, `vscode`, or`antigravity` on hook-sourced events, update them to `claude_code`, `codex_cli`,@@ -165,8 +187,8 @@ Stay up to date with the latest changes to the Agent Beacon CLI.`vscode_copilot` normalized to `copilot_cli`, two different products, and thecanonical name was not stable when normalized a second time.- **`endpoint doctor` can see an endpoint that captures nobody** · A system install- runs as root, so every harness check inspected root's configuration — which the- install had just written correctly — while the actual operator had none. The new+ runs as root, so every harness check inspected root's configuration, which the+ install had just written correctly, while the actual operator had none. The new`console_user_configured` check asks whether a real user's agent runtime points atthis collector, and fails loudly when it does not. Previously the only symptom wasa warning the documentation told you to ignore.@@ -217,7 +239,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.deployments, `--system` installs, CI, `--dry-run`, and piped input all skip it.Unattended installs can set `BEACON_ONBOARDING=0`, and fleet rollouts can supply`BEACON_ONBOARDING_EMAIL` and `BEACON_ONBOARDING_USAGE` to record attribution- with no terminal. Nothing Beacon captures is ever sent — no prompts, file+ with no terminal. Nothing Beacon captures is ever sent: no prompts, filecontents, commands, or telemetry events.- **`beacon endpoint onboarding`** · Shows what was recorded, clears it with`--reset`, or retries an undelivered signup with `--resend`. A failed submission@@ -471,13 +493,13 @@ Stay up to date with the latest changes to the Agent Beacon CLI.- **Agent skills inventory** · `beacon endpoint inventory` now discovers local agent skill manifests for Claude Code, Cursor, and `.agents/skills`, reporting names, paths, and content hashes for change detection. See the [Skills inventory guide](/inventory/skills).- **Skills in the local dashboard** · The Agent Inventory view in the local dashboard shows an Agent Skills table and summary card alongside agent harnesses and MCP servers, so operators can see installed skills at a glance.-- **Metadata-only by design** · Skill discovery records hashes and file paths only — `SKILL.md` instruction bodies are never read or stored, consistent with Beacon's [data inventory](/security/data-inventory) posture.+- **Metadata-only by design** · Skill discovery records hashes and file paths only. `SKILL.md` instruction bodies are never read or stored, consistent with Beacon's [data inventory](/security/data-inventory) posture.- **Optional inventory snapshot events** · Running inventory with `--write-event` appends metadata-only inventory heartbeat and snapshot events to `inventory_state.jsonl` so installed-skill state can be kept separate from runtime activity telemetry.### v0.0.67 · June 15, 2026- **Devin Cloud agent telemetry** · Added `beacon cloud devin pull` to capture autonomous [Devin Cloud agent](/runtimes/devin-cloud-agents) telemetry org-wide. Using a Devin organization service key, one central run pulls every user's cloud sessions from the Devin API, normalizes them into Beacon endpoint events (`provider=devin_cloud`), writes the runtime JSONL, and optionally uploads a per-session snapshot to a customer-managed GCS bucket. No per-user or per-sandbox setup is required.-- **Live and scheduled capture** · `--watch` polls continuously for near-real-time capture; a single sweep (the default) suits cron and CI runners. Re-runs are idempotent — events are deduplicated by Devin event id and unchanged sessions are skipped — and `--full-resync` re-fetches and re-uploads every session for backfills.+- **Live and scheduled capture** · `--watch` polls continuously for near-real-time capture; a single sweep (the default) suits cron and CI runners. Re-runs are idempotent, because events are deduplicated by Devin event id and unchanged sessions are skipped. `--full-resync` re-fetches and re-uploads every session for backfills.- **Per-user attribution** · Devin Cloud events carry the Devin session id as `run_id` and the Devin user id as `run.actor`, so org-wide telemetry stays attributable per end-user and forwards to any existing SIEM destination over the normalized runtime log. Telemetry is message-level (session lifecycle, prompts, agent messages, status, pull requests, and ACU usage); the Devin API does not expose per-tool or per-command events for autonomous sessions.### v0.0.66 · June 13, 2026@@ -885,7 +907,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.- **Telemetry defaults** · Beacon now writes structured Codex OTEL exporter configuration for logs, traces, and metrics while setting `log_user_prompt = false`.- **Noisy trace filtering** · Beacon filters noisy internal Codex transport traces so endpoint timelines focus on meaningful Codex activity instead of HTTP/2 framing and flow-control churn.-### Beacon Endpoint+### Beacon endpoint- **Endpoint telemetry** · Beacon now configures local agent harness telemetry and writes normalized endpoint events to local JSONL logs.- **Runtime discovery** · Beacon discovers supported local agent harnesses, including Claude Code, Codex CLI, Cursor, and Claude Cowork.diff --git a/docs/cli/ci-exec.mdx b/docs/cli/ci-exec.mdxindex d16e805a..e1d609e6 100644--- a/docs/cli/ci-exec.mdx+++ b/docs/cli/ci-exec.mdx@@ -3,7 +3,7 @@ title: "beacon ci exec"description: "Run a command with Beacon telemetry captured for a CI job"----## Command Overview+## Command overview`beacon ci exec` starts a temporary Beacon collector, runs the child command after `--`, stops the collector, validates the runtime log, and prints the artifact paths. The child command's exit code is preserved.diff --git a/docs/cli/ci-finish.mdx b/docs/cli/ci-finish.mdxindex c37949f2..7061dd4b 100644--- a/docs/cli/ci-finish.mdx+++ b/docs/cli/ci-finish.mdx@@ -3,7 +3,7 @@ title: "beacon ci finish"description: "Stop, validate, and export a detached Beacon CI telemetry session"----## Command Overview+## Command overview`beacon ci finish` loads the state file from `beacon ci start`, stops the collector, validates the runtime log, and optionally uploads the completed JSONL artifact.@@ -38,7 +38,7 @@ BEACON_CI_GCS_PREFIX="github-actions" \beacon ci finish --upload gcs```-## GitHub Actions Session+## GitHub Actions session```yaml- name: Start Beacon telemetrydiff --git a/docs/cli/ci-start.mdx b/docs/cli/ci-start.mdxindex 64585a78..3caebcc8 100644--- a/docs/cli/ci-start.mdx+++ b/docs/cli/ci-start.mdx@@ -3,7 +3,7 @@ title: "beacon ci start"description: "Start a detached Beacon CI telemetry session"----## Command Overview+## Command overview`beacon ci start` starts a local collector, writes a session state file, and prints or exports telemetry environment variables for later workflow steps.diff --git a/docs/cli/ci-validate.mdx b/docs/cli/ci-validate.mdxindex 97cb6682..cb8d3f52 100644--- a/docs/cli/ci-validate.mdx+++ b/docs/cli/ci-validate.mdx@@ -3,7 +3,7 @@ title: "beacon ci validate"description: "Validate Beacon CI runtime telemetry artifacts"----## Command Overview+## Command overview`beacon ci validate` checks that the runtime log exists, parses as Beacon JSONL, and contains at least the required number of matching harness events.diff --git a/docs/cli/ci.mdx b/docs/cli/ci.mdxindex 4388a3ca..14dcf9a4 100644--- a/docs/cli/ci.mdx+++ b/docs/cli/ci.mdx@@ -3,7 +3,7 @@ title: "CI Agent Telemetry"description: "Wrap agent commands and CI actions with ephemeral Beacon telemetry"----## Command Overview+## Command overview`beacon ci` wraps supported agent commands and agent-launching CI steps with ephemeral Beacon telemetry. It runs for a single CI job without installing a persistent endpoint service or modifying runner-wide harness configuration.@@ -19,7 +19,7 @@ Use `beacon ci exec` when the workflow runs an agent command directly. For multiFor artifact upload, object storage export, and downstream SIEM handoff patterns, see [CI Telemetry Exports](/log-forwarding/ci-telemetry-exports).-## Wrap Agent Runs+## Wrap agent runs`beacon ci exec` starts a temporary local collector, injects supported telemetry configuration into one child process, writes normalized endpoint events to a CI runtime log, then validates that matching events were captured.@@ -33,7 +33,7 @@ For example, wrap a Claude Code prompt in a GitHub Actions step:beacon ci exec -- claude -p "Review this pull request"```-## Wrap Agent Actions+## Wrap agent actionsSome workflows call a third-party action that launches the agent internally. In those cases, start a detached Beacon session before the action and finish it in a cleanup step.diff --git a/docs/cli/claude-cowork.mdx b/docs/cli/claude-cowork.mdxindex 7d4fa295..fb5ed831 100644--- a/docs/cli/claude-cowork.mdx+++ b/docs/cli/claude-cowork.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint integrations claude-cowork"description: "Set up Claude Cowork OpenTelemetry export for Beacon"----## Integration Command+## Integration commandClaude Cowork exports telemetry from Anthropic's service, so its OTLP endpoint must be reachable from the public internet. Beacon can print the settings you need for the Claude admin console and validate whether Cowork events are arriving in the local runtime log.diff --git a/docs/cli/cloud-claude-web-print-hooks.mdx b/docs/cli/cloud-claude-web-print-hooks.mdxindex 9b38efdb..a3f5338e 100644--- a/docs/cli/cloud-claude-web-print-hooks.mdx+++ b/docs/cli/cloud-claude-web-print-hooks.mdx@@ -3,7 +3,7 @@ title: "beacon cloud claude-web print-hooks"description: "Print Claude Code cloud hook settings"----## Command Overview+## Command overview`beacon cloud claude-web print-hooks` prints the Claude hook settings used by the setup script.diff --git a/docs/cli/cloud-claude-web-print-setup.mdx b/docs/cli/cloud-claude-web-print-setup.mdxindex b0422828..e1e6db1d 100644--- a/docs/cli/cloud-claude-web-print-setup.mdx+++ b/docs/cli/cloud-claude-web-print-setup.mdx@@ -3,7 +3,7 @@ title: "beacon cloud claude-web print-setup"description: "Print a Claude Code cloud environment setup script"----## Command Overview+## Command overview`beacon cloud claude-web print-setup` prints a Claude Code cloud environment setup script for a Beacon release.diff --git a/docs/cli/cloud-cursor-print-hooks.mdx b/docs/cli/cloud-cursor-print-hooks.mdxindex fe72754c..053d2216 100644--- a/docs/cli/cloud-cursor-print-hooks.mdx+++ b/docs/cli/cloud-cursor-print-hooks.mdx@@ -3,7 +3,7 @@ title: "beacon cloud cursor print-hooks"description: "Print Cursor cloud hook settings"----## Command Overview+## Command overview`beacon cloud cursor print-hooks` prints project-level Cursor hook settings fora cloud sandbox. Commit the rendered JSON to `.cursor/hooks.json` beforediff --git a/docs/cli/cloud-cursor-print-setup.mdx b/docs/cli/cloud-cursor-print-setup.mdxindex e3f4eca0..120d6304 100644--- a/docs/cli/cloud-cursor-print-setup.mdx+++ b/docs/cli/cloud-cursor-print-setup.mdx@@ -3,7 +3,7 @@ title: "beacon cloud cursor print-setup"description: "Print a Cursor cloud agent binary setup script"----## Command Overview+## Command overview`beacon cloud cursor print-setup` prints a Cursor cloud agent setup script forinstalling Beacon binaries in the cloud sandbox.diff --git a/docs/cli/cloud-gcs-setup.mdx b/docs/cli/cloud-gcs-setup.mdxindex dd1c8eb9..f35f29b9 100644--- a/docs/cli/cloud-gcs-setup.mdx+++ b/docs/cli/cloud-gcs-setup.mdx@@ -3,7 +3,7 @@ title: "beacon cloud gcs setup"description: "Create or print GCS setup commands for cloud-agent telemetry"----## Command Overview+## Command overview`beacon cloud gcs setup` creates or prints self-serve Google Cloud Storage setup commands for cloud-agent telemetry.diff --git a/docs/cli/cloud-s3-setup.mdx b/docs/cli/cloud-s3-setup.mdxindex 97f14d7e..b6fb89a8 100644--- a/docs/cli/cloud-s3-setup.mdx+++ b/docs/cli/cloud-s3-setup.mdx@@ -3,7 +3,7 @@ title: "beacon cloud s3 setup"description: "Create or print S3 setup commands for cloud-agent telemetry"----## Command Overview+## Command overview`beacon cloud s3 setup` creates or prints self-serve Amazon S3 setup commandsfor cloud-agent telemetry.diff --git a/docs/cli/cloud.mdx b/docs/cli/cloud.mdxindex 95210859..4349129b 100644--- a/docs/cli/cloud.mdx+++ b/docs/cli/cloud.mdx@@ -43,7 +43,7 @@ and [Cursor Cloud Agents](/runtimes/cursor-cloud-agents).</Card></Columns>-## Object Storage Setup Note+## Object storage setup noteThe GCS helper creates or validates a bucket, creates a dedicated uploaderservice account, grants object upload access, creates a service-account key, anddiff --git a/docs/cli/cloudwatch.mdx b/docs/cli/cloudwatch.mdxindex 84a30ee9..d5fa27d9 100644--- a/docs/cli/cloudwatch.mdx+++ b/docs/cli/cloudwatch.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint cloudwatch"description: "Generate AWS CloudWatch Logs forwarding content and validation events for Beacon endpoint events."----## Forwarding Command+## Forwarding commandUse `beacon endpoint cloudwatch` to generate AWS CloudWatch Logs forwarding content for Beacon endpoint events. The generated pack keeps Beacon as a local JSONL producer and helps your customer-managed Vector agent ship `runtime.jsonl` to a CloudWatch Logs log group.diff --git a/docs/cli/dashboard.mdx b/docs/cli/dashboard.mdxindex 67a793c4..65dbcefd 100644--- a/docs/cli/dashboard.mdx+++ b/docs/cli/dashboard.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint dashboard"description: "Run the local Beacon endpoint dashboard"----## Command Overview+## Command overviewBeacon includes a local-only dashboard for investigating the runtime JSONL log. The dashboard binds to loopback by default, has no external network dependency during normal use, and is intended for local investigation rather than remote administration.diff --git a/docs/cli/datadog.mdx b/docs/cli/datadog.mdxindex 1d793280..efbd9293 100644--- a/docs/cli/datadog.mdx+++ b/docs/cli/datadog.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint datadog"description: "Generate Datadog Agent custom log collection content and validation events for Beacon endpoint events."----## Forwarding Command+## Forwarding commandUse `beacon endpoint datadog` to generate Datadog Agent custom log collection content for Beacon endpoint events. The generated pack tails Beacon's local `runtime.jsonl` file with the Datadog Agent and tags events with `service:beacon-endpoint-agent`, `source:beacon`, `vendor:beacon`, and `product:endpoint-agent`.diff --git a/docs/cli/elastic.mdx b/docs/cli/elastic.mdxindex 5300bc86..e8d4e1de 100644--- a/docs/cli/elastic.mdx+++ b/docs/cli/elastic.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint elastic"description: "Generate Elastic content and run a local Elasticsearch, Kibana, and Filebeat validation stack for Beacon endpoint events."----## Forwarding Command+## Forwarding commandUse `beacon endpoint elastic` to generate Elastic integration content for Beacon endpoint events. The generated pack tails Beacon's local `runtime.jsonl` file with Filebeat or standalone Elastic Agent and installs Elasticsearch/Kibana assets around the `logs-beacon.endpoint-*` data stream pattern.diff --git a/docs/cli/endpoint-bundle-diagnostics.mdx b/docs/cli/endpoint-bundle-diagnostics.mdxindex dcfa0fff..a0fd8fe0 100644--- a/docs/cli/endpoint-bundle-diagnostics.mdx+++ b/docs/cli/endpoint-bundle-diagnostics.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint bundle-diagnostics"description: "Write a redacted local diagnostics bundle for Beacon endpoint support"----## Command Overview+## Command overview`beacon endpoint bundle-diagnostics` writes a redacted local diagnostics bundle for Beacon endpoint support and troubleshooting.@@ -13,7 +13,7 @@ beacon endpoint bundle-diagnostics --output ./beacon-diagnosticsThe bundle is designed for support workflows where an operator needs endpoint configuration, health, inventory, and runtime-log context without exposing secrets by default. Beacon redacts sensitive destination values and only includes runtime event data when explicitly requested.-## Bundle Contents+## Bundle contentsThe diagnostics bundle can include:diff --git a/docs/cli/endpoint-config.mdx b/docs/cli/endpoint-config.mdxindex 4903bc7a..d3217e66 100644--- a/docs/cli/endpoint-config.mdx+++ b/docs/cli/endpoint-config.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint config"description: "Inspect, validate, and update Beacon endpoint configuration"----## Command Overview+## Command overview`beacon endpoint config` inspects and safely updates the local Beacon endpoint configuration.diff --git a/docs/cli/endpoint-discover.mdx b/docs/cli/endpoint-discover.mdxindex 82e61993..7f8ee5a9 100644--- a/docs/cli/endpoint-discover.mdx+++ b/docs/cli/endpoint-discover.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint discover"description: "Discover supported local agent harnesses and their Beacon telemetry state"----## Command Overview+## Command overview`beacon endpoint discover` lists supported [agent harnesses](/runtimes) detected on the local host.diff --git a/docs/cli/endpoint-doctor.mdx b/docs/cli/endpoint-doctor.mdxindex ffa4cbe1..66b9d118 100644--- a/docs/cli/endpoint-doctor.mdx+++ b/docs/cli/endpoint-doctor.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint doctor"description: "Run local Beacon endpoint health checks"----## Command Overview+## Command overview`beacon endpoint doctor` runs local health checks for the Beacon endpoint agent and exits non-zero when any hard check fails. Add `--fix` to apply safe remediations for supported findings.@@ -32,11 +32,9 @@ The runtime log itself can be missing before the first event is written. In that### `console_user_configured`-System-mode only, and worth understanding because it is the one failure that a completely healthy-endpoint can still report.+System-mode only, and worth understanding because it is the one failure that a completely healthy endpoint can still report.-A system endpoint runs as root, so it has to work out *whose* agent settings to configure — the-collector is useless if nothing exports to it. This check asks whether that actually happened:+A system endpoint runs as root, so it has to work out whose agent settings to configure, and the collector is useless if nothing exports to it. This check asks whether that happened:```console_user_configured: fail target=alice (alice has no agent runtime pointed at this@@ -44,17 +42,13 @@ console_user_configured: fail target=alice (alice has no agent runtime pointed aaction="sudo beacon endpoint user-config repair-installed --system"```-Everything else can be green when this fails. The collector is running, the service is loaded, and-the harness check passes — because `doctor --system` runs as root and sees the settings the install-wrote for root, which are correct. The person whose sessions matter is the one with nothing.+Everything else can be green when this fails. The collector is running, the service is loaded, and the harness check passes, because `doctor --system` runs as root and sees the settings the install wrote for root. The person whose sessions matter is the one with nothing.-If no logged-in user can be identified at all, this reports a warning rather than a failure: an-unattended host legitimately has nobody to configure, and that is not something an operator can act-on.+If no logged-in user can be identified at all, this reports a warning rather than a failure: an unattended host legitimately has nobody to configure, and that is not something an operator can act on.## Fix mode-`beacon endpoint doctor --fix` plans and applies safe remediations for supported findings. It can create a missing runtime log, and recreate managed collector configuration and the service definition — a launchd plist or a systemd unit — when the endpoint configuration is valid.+`beacon endpoint doctor --fix` plans and applies safe remediations for supported findings. It can create a missing runtime log, and recreate managed collector configuration and the service definition (a launchd plist or a systemd unit) when the endpoint configuration is valid.Fix mode deliberately skips cases that need operator intent, such as invalid endpoint configuration, missing harness setup, missing observed runtime events, unsafe runtime log permissions, or service repair on a host with no service manager to repair. If a collector service repair fails, Beacon rolls back the files and service state it changed where possible, then refreshes doctor results so the printed checks reflect any partial fixes that succeeded.diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdxindex 7023eef7..2f056d6d 100644--- a/docs/cli/endpoint-install.mdx+++ b/docs/cli/endpoint-install.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint install"description: "Install or update the local Beacon endpoint collector and runtime telemetry"----## Command Overview+## Command overview`beacon endpoint install` configures the local endpoint agent, writes the OpenTelemetry Collector configuration, installs the collector service, configures selected agent harnesses, and optionally adds Splunk HEC or Falcon LogScale HEC collector destinations.diff --git a/docs/cli/endpoint-inventory.mdx b/docs/cli/endpoint-inventory.mdxindex d7ddd6b4..72eb2891 100644--- a/docs/cli/endpoint-inventory.mdx+++ b/docs/cli/endpoint-inventory.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint inventory"description: "Show installed, configured, and observed Beacon endpoint inventory"----## Command Overview+## Command overview`beacon endpoint inventory` shows Beacon endpoint inventory across configured harnesses, detected local runtimes, hook integrations, and observed runtime events.@@ -15,7 +15,7 @@ Use inventory when you need a fleet-friendly view of what Beacon is configured t`beacon inventory` is a top-level alias for `beacon endpoint inventory`.-## Inventory Data+## Inventory dataInventory can include:@@ -37,7 +37,7 @@ Use the section filters when you only need one inventory surface:The section filters can be combined. For example, `--mcp --skills --json` prints only MCP and skill inventory buckets in the JSON output.-## Capturing Full Definitions+## Capturing full definitionsBy default inventory is metadata- and hash-only: it reports paths, hashes, MCP transport, command basenames, argument counts, and safe environment key names, but never the raw file bodies.@@ -58,7 +58,7 @@ beacon endpoint inventory --mcp --contentsContent capture is opt-in and offline; `--contents` only reads files inventory already inspects locally.-## Inventory Heartbeats+## Inventory heartbeatsEndpoint hooks can periodically append inventory telemetry to a separate `inventory_state.jsonl` file beside `runtime.jsonl`. The hook that fires is recorded as trigger provenance, but the default heartbeat scans all supported local inventory candidates:diff --git a/docs/cli/endpoint-onboarding.mdx b/docs/cli/endpoint-onboarding.mdxindex 1bfed617..89225d26 100644--- a/docs/cli/endpoint-onboarding.mdx+++ b/docs/cli/endpoint-onboarding.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint onboarding"description: "Show, reset, or resend the one-time Beacon onboarding record"----## Command Overview+## Command overview`beacon endpoint onboarding` inspects the one-time onboarding record written the firsttime `beacon endpoint install` runs in a terminal.@@ -17,8 +17,7 @@ Beacon does not ask again.## First-run onboarding-The first interactive `beacon endpoint install` asks two questions — how you are using-Beacon, and your email — and sends the answers to Asymptote once. This is how we decide+The first interactive `beacon endpoint install` asks two questions, how you are using Beacon and your email, then sends the answers to Asymptote once. This is how we decidewhich agent runtimes and integrations to build next.What is sent, and nothing else:diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdxindex bac705c3..981e26ff 100644--- a/docs/cli/endpoint-paths.mdx+++ b/docs/cli/endpoint-paths.mdx@@ -3,7 +3,7 @@ title: "Endpoint Paths and Ports"description: "Review Beacon user-mode and system-mode paths, ports, and hook locations"----## File Locations+## File locationsBeacon manages different paths depending on whether you install in user mode or system mode. The active runtime log stays at `runtime.jsonl` and rotates at 10 MiB, retaining five numbered local archives by default.@@ -15,37 +15,28 @@ Beacon manages different paths depending on whether you install in user mode or| Rotated runtime archives | `~/.beacon/endpoint/logs/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` | `%ProgramData%\Beacon\Endpoint\logs\runtime.jsonl.1` through `.5` || Threat rule store | `~/.beacon/endpoint/rules` | `/Library/Application Support/Beacon/Endpoint/rules` | `/etc/beacon/endpoint/rules` | `%ProgramData%\Beacon\Endpoint\rules` || Collector config | `~/.beacon/endpoint/otelcol.yaml` | `/Library/Application Support/Beacon/Endpoint/otelcol.yaml` | `/etc/beacon/endpoint/otelcol.yaml` | `%ProgramData%\Beacon\Endpoint\otelcol.yaml` |-| Installed binaries | — | `/opt/beacon/bin` | `/opt/beacon/bin` | `%ProgramFiles%\Beacon\bin` |+| Installed binaries | None | `/opt/beacon/bin` | `/opt/beacon/bin` | `%ProgramFiles%\Beacon\bin` || OTLP gRPC | `127.0.0.1:4317` | `127.0.0.1:4317` | `127.0.0.1:4317` | `127.0.0.1:4317` || OTLP HTTP | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` |-On Windows the system log directory sits under the base directory rather than in a separate location,-because there is no `/var/log` equivalent. `%ProgramData%` and `%ProgramFiles%` are read from the-environment rather than hardcoded, so a relocated or localized install is found rather than missed.+On Windows the system log directory sits under the base directory rather than in a separate location, because there is no `/var/log` equivalent. `%ProgramData%` and `%ProgramFiles%` are read from the environment rather than hardcoded, so a relocated or localized install is found rather than missed.-## Service Definitions+## Service definitions-The collector runs under whichever service manager the host provides. On Linux, Beacon picks it by looking at-what is actually running as PID 1, not at which tools are installed, so a container with-`systemctl` on `PATH` but no systemd still gets the supervised fallback.+The collector runs under whichever service manager the host provides. On Linux, Beacon picks it by looking at what is actually running as PID 1, not at which tools are installed, so a container with `systemctl` on `PATH` but no systemd still gets the supervised fallback.| Platform | Service manager | System mode | User mode ||---|---|---|---|| macOS | launchd | `/Library/LaunchDaemons/com.beacon.endpoint.collector.plist` | `~/Library/LaunchAgents/com.beacon.endpoint.collector.user.plist` || Linux | systemd | `/etc/systemd/system/beacon-collector.service` | `~/.config/systemd/user/beacon-collector.service` |-| Windows | Service Control Manager | `BeaconCollector` service, defined at `HKLM\SYSTEM\CurrentControlSet\Services\BeaconCollector` | supervised — Windows has no per-user service manager |+| Windows | Service Control Manager | `BeaconCollector` service, defined at `HKLM\SYSTEM\CurrentControlSet\Services\BeaconCollector` | Supervised, because Windows has no per-user service manager || Containers, no init | supervised | `/etc/beacon/endpoint/collector.pid` | `~/.beacon/endpoint/collector.pid` |-Windows has no unit file to point at: the service definition lives in the registry, so that is what-`beacon endpoint status` reports where the other platforms report a path. And there is no counterpart-to `systemctl --user` or launchd's per-user domain, so a Windows user-mode install always gets the-supervised collector — see [Windows install](/platforms/windows#user-mode-install).+Windows has no unit file to point at: the service definition lives in the registry, so that is what `beacon endpoint status` reports where the other platforms report a path. And there is no counterpart to `systemctl --user` or launchd's per-user domain, so a Windows user-mode install always gets the supervised collector. See [Windows install](/platforms/windows#user-mode-install).-A supervised collector is a plain background process tracked by a pidfile. It works, but nothing-restarts it if it exits or when the machine reboots — `beacon endpoint status` says so explicitly-rather than reporting the same health as a real service.+A supervised collector is a plain background process tracked by a pidfile. It works, but nothing restarts it if it exits or when the machine reboots. `beacon endpoint status` says so explicitly rather than reporting the same health as a real service.-Antigravity CLI, Claude Code, Cline, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, OpenCode, and Qwen Code hooks install an embedded `beacon-hooks` adapter under the Beacon endpoint base directory.+Hooks, plugins, and extensions install an embedded `beacon-hooks` adapter under the Beacon endpoint base directory.Hook and plugin configuration is written to:@@ -53,14 +44,15 @@ Hook and plugin configuration is written to:|---|---|---|| Antigravity CLI | `~/.gemini/config/hooks.json` | `./.agents/hooks.json` || Claude Code | `~/.claude/settings.json` | `./.claude/settings.json` |+| Cline | `~/.cline/plugins/beacon.ts` | `./.cline/plugins/beacon.ts` || Cursor | `~/.cursor/hooks.json` | `./.cursor/hooks.json` || Devin CLI | `~/.config/devin/config.json` | `./.devin/hooks.v1.json` || Devin Desktop | `~/.codeium/windsurf/hooks.json` | `./.windsurf/hooks.json` || Factory | `~/.factory/settings.json` | `./.factory/settings.json` || Grok Build | `~/.grok/hooks/beacon-endpoint.json` | `./.grok/hooks/beacon-endpoint.json` |-| Hermes Agent | `~/.hermes/config.yaml` | — |+| Hermes Agent | `~/.hermes/config.yaml` | Not supported || OpenCode | `~/.config/opencode/plugins/beacon.ts` | `./.opencode/plugins/beacon.ts` |-| Cline | `~/.cline/plugins/beacon.ts` | `./.cline/plugins/beacon.ts` |+| Pi | `~/.pi/agent/extensions/beacon.ts` | `./.pi/extensions/beacon.ts` || Qwen Code | `~/.qwen/settings.json` | `./.qwen/settings.json` |## Relateddiff --git a/docs/cli/endpoint-repair.mdx b/docs/cli/endpoint-repair.mdxindex 1587e58b..389486fb 100644--- a/docs/cli/endpoint-repair.mdx+++ b/docs/cli/endpoint-repair.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint repair"description: "Repair Beacon endpoint service files, collector configuration, and telemetry settings"----## Command Overview+## Command overview`beacon endpoint repair` reapplies Beacon endpoint service files, collector configuration, harness telemetry configuration, and optional destinations such as Splunk HEC or Falcon LogScale HEC. It is useful after upgrading Beacon, changing ports, changing SIEM settings, or correcting local configuration drift.diff --git a/docs/cli/endpoint-status.mdx b/docs/cli/endpoint-status.mdxindex 19202b08..bd5000fc 100644--- a/docs/cli/endpoint-status.mdx+++ b/docs/cli/endpoint-status.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint status"description: "Inspect local Beacon endpoint health, diagnostics, and runtime log state"----## Command Overview+## Command overview`beacon endpoint status` reports the current local endpoint configuration, collector status, service state, discovered harnesses, diagnostics, destination status, and the last observed Beacon event.diff --git a/docs/cli/endpoint-test-event.mdx b/docs/cli/endpoint-test-event.mdxindex b8abb83e..d8e5c45d 100644--- a/docs/cli/endpoint-test-event.mdx+++ b/docs/cli/endpoint-test-event.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint test-event"description: "Write a synthetic Beacon endpoint validation event"----## Command Overview+## Command overview`beacon endpoint test-event` writes a synthetic validation event to the Beacon runtime JSONL log.diff --git a/docs/cli/endpoint-uninstall.mdx b/docs/cli/endpoint-uninstall.mdxindex 46e01e53..6b7ac66f 100644--- a/docs/cli/endpoint-uninstall.mdx+++ b/docs/cli/endpoint-uninstall.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint uninstall"description: "Remove Beacon endpoint service files while optionally preserving logs or runtime configuration"----## Command Overview+## Command overview`beacon endpoint uninstall` unloads the local Beacon service and removes managed endpoint files.diff --git a/docs/cli/endpoint.mdx b/docs/cli/endpoint.mdxindex 7e5b1a4e..0a2aab8e 100644--- a/docs/cli/endpoint.mdx+++ b/docs/cli/endpoint.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint"description: "Install, inspect, repair, and remove the Beacon endpoint agent"----## Command Overview+## Command overviewThe `beacon endpoint` command group manages the local Beacon [endpoint agent](/concepts/core-concepts#endpoint-agent). It configures agent harness telemetry, runs a [local OpenTelemetry Collector](/concepts/core-concepts#local-collector), writes Beacon [endpoint events](/concepts/core-concepts#endpoint-event) to JSONL, and exposes subcommands for local inspection and integrations. Endpoint commands use per-user paths by default; pass `--system` for root-managed package or MDM deployments.@@ -57,7 +57,7 @@ beacon endpoint [command]Additional endpoint commands: [`inventory`](/cli/endpoint-inventory), [`discover`](/cli/endpoint-discover), [`test-event`](/cli/endpoint-test-event), and [`bundle-diagnostics`](/cli/endpoint-bundle-diagnostics).-## Common Paths+## Common paths| Item | User mode | System mode ||------|-----------|-------------|@@ -66,7 +66,7 @@ Additional endpoint commands: [`inventory`](/cli/endpoint-inventory), [`discover| Runtime log | `~/.beacon/endpoint/logs/runtime.jsonl` | `/var/log/beacon-agent/runtime.jsonl` || Collector config | `~/.beacon/endpoint/otelcol.yaml` | `/Library/Application Support/Beacon/Endpoint/otelcol.yaml` |-## Related Groups+## Related groups<Columns cols={2}><Card title="Core Concepts" icon="book-open" href="/concepts/core-concepts">diff --git a/docs/cli/gcs.mdx b/docs/cli/gcs.mdxindex 672baf57..d8c59a52 100644--- a/docs/cli/gcs.mdx+++ b/docs/cli/gcs.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint gcs"description: "Generate Google Cloud Storage forwarding content and validation events for Beacon endpoint events."----## Forwarding Command+## Forwarding commandUse `beacon endpoint gcs` to generate Google Cloud Storage forwarding content for Beacon endpoint events. The generated pack keeps Beacon as a local JSONL producer and helps your customer-managed Vector agent upload runtime and inventory JSONL to a GCS bucket as NDJSON.diff --git a/docs/cli/hooks.mdx b/docs/cli/hooks.mdxindex c741cca1..e4c7c900 100644--- a/docs/cli/hooks.mdx+++ b/docs/cli/hooks.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint hooks"description: "Install and manage Beacon endpoint hooks for supported agent harnesses"----## Command Overview+## Command overviewBeacon can install [hook-based endpoint telemetry](/concepts/core-concepts#hooks) for supported [agent harnesses](/runtimes). The hook adapter emits local Beacon [endpoint events](/concepts/core-concepts#endpoint-event) for sessions, prompt submission, tool use, command execution, MCP-like tool activity, approval decisions, permissions, diffs, and file edits where each runtime exposes those hook payloads.@@ -427,18 +427,18 @@ If Hermes telemetry is missing, confirm `~/.hermes/config.yaml` contains command## Qwen Code troubleshooting-Beacon merges its hooks into Qwen Code's own `settings.json` — `~/.qwen/settings.json` for user-level installs, `./.qwen/settings.json` for project-level installs. Unrelated top-level keys and non-Beacon hooks in the same event group are preserved, and a re-install replaces Beacon's own entries instead of adding a second copy. Beacon identifies its entries by the `--platform qwen` argument in the hook command, since it has no file of its own in `~/.qwen` to stamp.+Beacon merges its hooks into Qwen Code's own `settings.json`: `~/.qwen/settings.json` for user-level installs, `./.qwen/settings.json` for project-level installs. Unrelated top-level keys and non-Beacon hooks in the same event group are preserved, and a re-install replaces Beacon's own entries instead of adding a second copy. Beacon identifies its entries by the `--platform qwen` argument in the hook command, since it has no file of its own in `~/.qwen` to stamp.Qwen Code is a Gemini CLI fork without Gemini's OpenTelemetry export, so hooks are the only collection path for this runtime. `beacon endpoint install --harness qwen` fails with a message pointing here rather than appearing to succeed.Two Qwen-specific details are worth knowing before hand-editing the file:- **Timeouts are milliseconds, not seconds.** Claude Code reads `timeout` as seconds, so a Claude-style `10` means 10 ms to Qwen and every tool event is killed mid-write while the install still reports success. Beacon writes millisecond values (30000 for prompt submission, 10000 for tool events, 45000 for stop); events with no entry inherit Qwen's own 60000 ms default.-- **Hooks declare `shell: bash`.** Qwen only uses bash when the hook configuration asks for it. Left unset on Windows it falls back to `cmd.exe`, which cannot parse Beacon's POSIX-quoted command, so every hook fails to start. This requires `bash` on `PATH` on Windows — the same requirement Claude Code already carries there.+- **Hooks declare `shell: bash`.** Qwen only uses bash when the hook configuration asks for it. Left unset on Windows it falls back to `cmd.exe`, which cannot parse Beacon's POSIX-quoted command, so every hook fails to start. This requires `bash` on `PATH` on Windows, the same requirement Claude Code already carries there.If Qwen telemetry is missing, check the selected level, confirm `settings.json` contains commands with `--platform qwen`, confirm `disableAllHooks` is not set in Qwen's settings, confirm hook timeouts are millisecond values, trust the folder for a project-level install, and restart Qwen so new sessions pick up the updated settings.-Beacon's `PreToolUse` hook answers with an empty object on purpose. Qwen reads `hookSpecificOutput.permissionDecision` from that hook, where `allow` means *run the tool without the usual approval prompt* — so an observing hook that answered `allow` would silently disarm your own permission prompts. Approval telemetry comes from Qwen's `PermissionRequest` event instead.+Beacon's `PreToolUse` hook answers with an empty object on purpose. Qwen reads `hookSpecificOutput.permissionDecision` from that hook, where `allow` means run the tool without the usual approval prompt, so an observing hook that answered `allow` would silently disarm your own permission prompts. Approval telemetry comes from Qwen's `PermissionRequest` event instead.## Codex CLI troubleshootingdiff --git a/docs/cli/index.mdx b/docs/cli/index.mdxindex 5ce31d53..abd96a00 100644--- a/docs/cli/index.mdx+++ b/docs/cli/index.mdx@@ -7,7 +7,7 @@ description: "Agent Beacon CLI command manual organized by command group"Use this reference to browse Beacon commands by hierarchy. Each command links to the consolidated guide section with examples, flags, and operational notes.-## Install and Upgrade+## Install and upgradeInstall the Beacon CLI, check for released updates, and repair endpoint configuration after upgrades:diff --git a/docs/cli/ingest-endpoint.mdx b/docs/cli/ingest-endpoint.mdxindex 7e8e9964..e6a40d3a 100644--- a/docs/cli/ingest-endpoint.mdx+++ b/docs/cli/ingest-endpoint.mdx@@ -3,7 +3,7 @@ title: "beacon ingest endpoint"description: "Check and upload endpoint telemetry for managed ingest"----## Command Overview+## Command overview`beacon ingest endpoint` manages endpoint telemetry uploads to Asymptote Managed ingest.diff --git a/docs/cli/ingest.mdx b/docs/cli/ingest.mdxindex f7a0d85b..d9b542f2 100644--- a/docs/cli/ingest.mdx+++ b/docs/cli/ingest.mdx@@ -4,7 +4,7 @@ description: "Upload Beacon telemetry to configured ingest destinations"tag: "Enterprise"----## Command Overview+## Command overview`beacon ingest` shows managed ingest status and uploads endpoint telemetry to configured Asymptote Managed destinations.@@ -29,7 +29,7 @@ Use these commands when an endpoint is configured for managed ingest and you nee</Card></Columns>-## Shared Flags+## Shared flags`beacon ingest status`, `beacon ingest endpoint status`, and `beacon ingest endpoint upload` accept the same endpoint selection and output flags.diff --git a/docs/cli/install.mdx b/docs/cli/install.mdxindex b465612f..3cc58941 100644--- a/docs/cli/install.mdx+++ b/docs/cli/install.mdx@@ -5,8 +5,7 @@ description: "Install the Beacon CLI with Homebrew or platform archives"## Choose your platform-This page installs the **CLI**. Setting up the endpoint agent — the local collector that captures-agent activity — differs by operating system, so start with your platform:+This page installs the **CLI**. Setting up the endpoint agent, the local collector that captures agent activity, differs by operating system, so start with your platform:<Columns cols={2}><Card title="macOS" icon="apple" href="/platforms/macos">diff --git a/docs/cli/login.mdx b/docs/cli/login.mdxindex eb3a9290..cd0fd094 100644--- a/docs/cli/login.mdx+++ b/docs/cli/login.mdx@@ -4,7 +4,7 @@ description: "Log in to the Asymptote dashboard from the Beacon CLI"tag: "Enterprise"----## Command Overview+## Command overviewAuthenticate the Beacon CLI with your Asymptote dashboard account. The command opens a browser-based authorization flow and saves credentials for Beacon features that need dashboard access.diff --git a/docs/cli/manual-install.mdx b/docs/cli/manual-install.mdxindex b25b50ff..850b84f5 100644--- a/docs/cli/manual-install.mdx+++ b/docs/cli/manual-install.mdx@@ -3,12 +3,10 @@ title: "Manual CLI Installation"description: "Install the Beacon CLI from platform archives or build it from source"----## Archive Collection+## Archive collectionBeacon releases publish platform archives for macOS and Linux on `amd64` and `arm64`, plus a-`.zip` for Windows. Each archive contains three binaries — the `beacon` CLI, the `beacon-hooks`-adapter that captures tool activity, and the matching `beacon-otelcol` collector — with SHA-256-checksums published alongside the release in `checksums.txt`.+`.zip` for Windows. Each archive contains three binaries: the `beacon` CLI, the `beacon-hooks` adapter that captures tool activity, and the matching `beacon-otelcol` collector. SHA-256 checksums are published alongside the release in `checksums.txt`.All three matter. `beacon-hooks` is what supported runtimes invoke to record prompts, tool calls,and approvals, so an install that keeps only the CLI and the collector captures OpenTelemetry datadiff --git a/docs/cli/mcp-doctor.mdx b/docs/cli/mcp-doctor.mdxindex 243b7259..ac46c064 100644--- a/docs/cli/mcp-doctor.mdx+++ b/docs/cli/mcp-doctor.mdx@@ -3,7 +3,7 @@ title: "beacon mcp doctor"description: "Validate local Beacon MCP setup"----## Command Overview+## Command overview`beacon mcp doctor` validates local Beacon MCP setup before you connect an MCP client.@@ -77,7 +77,7 @@ sudo beacon mcp doctor --system<Card title="Test MCP Access" icon="server" href="/guides/local-testing/mcp">Understand Beacon MCP and test local client access.</Card>- <Card title="Connect Cursor and Claude Code" icon="plug" href="/guides/local-testing/mcp#connect-cursor-and-claude-code">+ <Card title="Connect Cursor and Claude Code" icon="plug" href="/guides/local-testing/mcp#4-connect-cursor-and-claude-code">Install Beacon MCP in local assistant clients.</Card></Columns>diff --git a/docs/cli/mcp-serve.mdx b/docs/cli/mcp-serve.mdxindex b903521b..58672b7a 100644--- a/docs/cli/mcp-serve.mdx+++ b/docs/cli/mcp-serve.mdx@@ -3,7 +3,7 @@ title: "beacon mcp serve"description: "Run the local Beacon MCP server"----## Command Overview+## Command overview`beacon mcp serve` starts the local Beacon MCP server over stdio or loopback HTTP JSON-RPC.@@ -76,7 +76,7 @@ beacon mcp serve --log-path /path/to/runtime.jsonl<Card title="beacon mcp doctor" icon="stethoscope" href="/cli/mcp-doctor">Validate local Beacon MCP setup before connecting a client.</Card>- <Card title="Connect Cursor and Claude Code" icon="plug" href="/guides/local-testing/mcp#connect-cursor-and-claude-code">+ <Card title="Connect Cursor and Claude Code" icon="plug" href="/guides/local-testing/mcp#4-connect-cursor-and-claude-code">Install Beacon MCP in local assistant clients.</Card></Columns>diff --git a/docs/cli/mcp.mdx b/docs/cli/mcp.mdxindex 045bb0cf..dd90dae0 100644--- a/docs/cli/mcp.mdx+++ b/docs/cli/mcp.mdx@@ -3,7 +3,7 @@ title: "beacon mcp"description: "Expose local Beacon activity to MCP clients"----## Command Overview+## Command overviewThe `beacon mcp` command group exposes local Beacon endpoint activity to MCP clients so an assistant can search, summarize, and retrieve compact event records from the local `runtime.jsonl` log.@@ -63,7 +63,7 @@ Search and summary tools accept filters such as `since`, `until`, `limit`, `q`,<Card title="beacon mcp doctor" icon="stethoscope" href="/cli/mcp-doctor">Validate local Beacon MCP setup.</Card>- <Card title="Connect Cursor and Claude Code" icon="plug" href="/guides/local-testing/mcp#connect-cursor-and-claude-code">+ <Card title="Connect Cursor and Claude Code" icon="plug" href="/guides/local-testing/mcp#4-connect-cursor-and-claude-code">Install Beacon MCP in local assistant clients.</Card><Card title="Dashboard" icon="chart-line" href="/cli/dashboard">diff --git a/docs/cli/openclaw.mdx b/docs/cli/openclaw.mdxindex 6d930b50..fe4280fe 100644--- a/docs/cli/openclaw.mdx+++ b/docs/cli/openclaw.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint integrations openclaw"description: "Set up OpenClaw Gateway OpenTelemetry export for Beacon"----## Integration Command+## Integration commandOpenClaw Gateway can export diagnostics through the `diagnostics-otel` plugin. Beacon can print a local OTLP/HTTP Gateway configuration and validate whether OpenClaw-derived events are arriving in the endpoint runtime log.diff --git a/docs/cli/rapid7.mdx b/docs/cli/rapid7.mdxindex 729485f6..f32a3bbd 100644--- a/docs/cli/rapid7.mdx+++ b/docs/cli/rapid7.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint rapid7"description: "Generate Rapid7 InsightIDR Custom Logs forwarding content and validation events for Beacon endpoint events."----## Forwarding Command+## Forwarding commandUse `beacon endpoint rapid7` to generate Rapid7 InsightIDR Custom Logs forwarding content for Beacon endpoint events. The generated pack keeps Beacon as a local JSONL producer and helps your customer-managed shipper upload `runtime.jsonl` to a Rapid7 Custom Logs webhook event source.diff --git a/docs/cli/rules-add.mdx b/docs/cli/rules-add.mdxindex 428a7584..2d6da25e 100644--- a/docs/cli/rules-add.mdx+++ b/docs/cli/rules-add.mdx@@ -3,7 +3,7 @@ title: "beacon rules add"description: "Install local Beacon threat-detection rule files into the store"----## Command Overview+## Command overview`beacon rules add` installs a local `.rule.yaml` file or a directory of rule files into the local threat-rule store.diff --git a/docs/cli/rules-fields.mdx b/docs/cli/rules-fields.mdxindex c89717ac..654a9c70 100644--- a/docs/cli/rules-fields.mdx+++ b/docs/cli/rules-fields.mdx@@ -3,7 +3,7 @@ title: "beacon rules fields"description: "Print Beacon endpoint event fields available to threat-rule CEL expressions"----## Command Overview+## Command overview`beacon rules fields` prints the endpoint event fields that threat-rule CEL expressions can match on.diff --git a/docs/cli/rules-lint.mdx b/docs/cli/rules-lint.mdxindex 12a228ea..b1b43c51 100644--- a/docs/cli/rules-lint.mdx+++ b/docs/cli/rules-lint.mdx@@ -3,7 +3,7 @@ title: "beacon rules lint"description: "Validate Beacon threat-rule files and run embedded conformance fixtures"----## Command Overview+## Command overview`beacon rules lint` validates rule files and runs their embedded conformance fixtures.diff --git a/docs/cli/rules-list.mdx b/docs/cli/rules-list.mdxindex be869d8c..885586eb 100644--- a/docs/cli/rules-list.mdx+++ b/docs/cli/rules-list.mdx@@ -3,7 +3,7 @@ title: "beacon rules list"description: "List active Beacon threat-detection rules"----## Command Overview+## Command overview`beacon rules list` prints the active threat-detection rules used by [`beacon scan`](/cli/scan).diff --git a/docs/cli/rules-pull.mdx b/docs/cli/rules-pull.mdxindex 33834645..f98969c5 100644--- a/docs/cli/rules-pull.mdx+++ b/docs/cli/rules-pull.mdx@@ -3,7 +3,7 @@ title: "beacon rules pull"description: "Fetch an explicit Beacon threat-rule pack into the local store"----## Command Overview+## Command overview`beacon rules pull` downloads a rule file or rule pack from an explicit URL and installs valid rules into the local store.diff --git a/docs/cli/rules-remove.mdx b/docs/cli/rules-remove.mdxindex b312234d..fce1c5c6 100644--- a/docs/cli/rules-remove.mdx+++ b/docs/cli/rules-remove.mdx@@ -3,7 +3,7 @@ title: "beacon rules remove"description: "Remove a Beacon threat-detection rule from the local store"----## Command Overview+## Command overview`beacon rules remove` removes one installed threat-detection rule from the local store by rule id.diff --git a/docs/cli/rules.mdx b/docs/cli/rules.mdxindex d319a6ac..4b7e9840 100644--- a/docs/cli/rules.mdx+++ b/docs/cli/rules.mdx@@ -3,7 +3,7 @@ title: "beacon rules"description: "Manage and author Beacon threat-detection rules"----## Command Overview+## Command overview`beacon rules` manages the local threat-rule store used by [`beacon scan`](/cli/scan) and provides authoring helpers for validating rule packs.@@ -137,7 +137,7 @@ Render a markdown field reference:beacon rules fields --markdown```-## Shared Store Flags+## Shared store flags`beacon rules list`, `add`, `remove`, and `pull` accept endpoint mode flags:diff --git a/docs/cli/s3.mdx b/docs/cli/s3.mdxindex 4740937b..a34039f1 100644--- a/docs/cli/s3.mdx+++ b/docs/cli/s3.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint s3"description: "Generate AWS S3 forwarding content and validation events for Beacon endpoint events."----## Forwarding Command+## Forwarding commandUse `beacon endpoint s3` to generate AWS S3 forwarding content for Beacon endpoint events. The generated pack keeps Beacon as a local JSONL producer and helps your customer-managed Vector agent upload `runtime.jsonl` to an S3 bucket as gzip-compressed NDJSON.@@ -170,7 +170,7 @@ vendor=beacon product=endpoint-agent destination.type=s3 destination.mode=aws_s3| `--system` | Use system endpoint paths and launch daemon || `--log-path <path>` | Runtime JSONL log path |-## macOS MDM Credential Injection+## macOS MDM credential injectionFor a managed macOS package, run `/opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh` from MDM or a root shell with destination settings in the environment. The helper writes non-secret forwarding settings and any set AWS provider-chain variables to `/Library/Application Support/Beacon/Forwarders/s3-vector.env` with mode `0600`, then starts `com.beacon.endpoint.s3-forwarder`.diff --git a/docs/cli/scan-ci-gates.mdx b/docs/cli/scan-ci-gates.mdxindex 1d5b3691..4ba36067 100644--- a/docs/cli/scan-ci-gates.mdx+++ b/docs/cli/scan-ci-gates.mdx@@ -1,9 +1,9 @@----title: "Use scan gates"+title: "Use Scan Gates"description: "Filter Beacon scan findings and fail automation on severity thresholds"----## Command Overview+## Command overview`beacon scan` can filter displayed findings and return a non-zero exit code when findings meet a severity threshold.diff --git a/docs/cli/scan-local.mdx b/docs/cli/scan-local.mdxindex 3fddcc17..c82191a4 100644--- a/docs/cli/scan-local.mdx+++ b/docs/cli/scan-local.mdx@@ -1,9 +1,9 @@----title: "Run local scans"+title: "Run Local Scans"description: "Scan local Beacon endpoint telemetry with active threat-detection rules"----## Command Overview+## Command overviewRun `beacon scan` after endpoint telemetry is flowing to evaluate the runtime log with active threat-detection rules.diff --git a/docs/cli/scan.mdx b/docs/cli/scan.mdxindex 84765e9b..5d923698 100644--- a/docs/cli/scan.mdx+++ b/docs/cli/scan.mdx@@ -3,7 +3,7 @@ title: "beacon scan"description: "Run threat-detection rules over local Beacon endpoint telemetry"----## Command Overview+## Command overview`beacon scan` runs active threat-detection rules over the local Beacon runtime log and reports findings. The scan is read-only and never touches the network.diff --git a/docs/cli/sentinel.mdx b/docs/cli/sentinel.mdxindex 0f769906..c003cea8 100644--- a/docs/cli/sentinel.mdx+++ b/docs/cli/sentinel.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint sentinel"description: "Generate Microsoft Sentinel Azure Monitor Agent forwarding content and validation events for Beacon endpoint events."----## Forwarding Command+## Forwarding commandUse `beacon endpoint sentinel` to generate Microsoft Sentinel forwarding content for Beacon endpoint events. The generated pack keeps Beacon as a local JSONL producer and helps Azure Monitor Agent tail `runtime.jsonl` into a Log Analytics custom table through a Data Collection Rule.diff --git a/docs/cli/sumo.mdx b/docs/cli/sumo.mdxindex 15614be8..13a1e369 100644--- a/docs/cli/sumo.mdx+++ b/docs/cli/sumo.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint sumo"description: "Generate Sumo Logic HTTP Source forwarding content and validation events for Beacon endpoint events."----## Forwarding Command+## Forwarding commandUse `beacon endpoint sumo` to generate Sumo Logic HTTP Source forwarding content for Beacon endpoint events. The generated pack keeps Beacon as a local JSONL producer and helps your customer-managed shipper upload `runtime.jsonl` to a Sumo Logic Hosted Collector HTTP Logs & Metrics Source.diff --git a/docs/cli/token-usage.mdx b/docs/cli/token-usage.mdxindex 128bdf09..294225be 100644--- a/docs/cli/token-usage.mdx+++ b/docs/cli/token-usage.mdx@@ -3,7 +3,7 @@ title: "beacon token-usage"description: "Report token usage and attribution from Beacon runtime logs"----## Command Overview+## Command overview`beacon token-usage` reads Beacon runtime events from the JSONL log and summarizes token usage, cost, models, sessions, runs, harnesses, and repositories.@@ -19,7 +19,7 @@ Use this command when you need a local report before opening the dashboard, send## How token attribution works-Beacon normalizes token telemetry from every runtime into one canonical [`gen_ai.usage`](/telemetry-schema/normalization#usage-metadata) representation, then aggregates it locally from the runtime JSONL log. There are no per-harness token fields — a report over mixed runtimes uses the same vocabulary throughout.+Beacon normalizes token telemetry from every runtime into one canonical [`gen_ai.usage`](/telemetry-schema/normalization#usage-metadata) representation, then aggregates it locally from the runtime JSONL log. There are no per-harness token fields, so a report over mixed runtimes uses the same vocabulary throughout.A few rules shape how the numbers read:@@ -35,7 +35,7 @@ A few rules shape how the numbers read:| Claude Code | input, output, cache read, cache creation, reasoning | Reported (`cost_usd`) | Yes || Codex CLI | input, output, cache read, reasoning | Not emitted by Codex | No (metric carries no conversation id) |-`cost_usd` and `--session` detail are empty for Codex because Codex does not emit a cost signal or a conversation id on its usage metric — not a Beacon limitation. See the [Codex CLI](/runtimes/codex-cli#token-usage-and-cost) and [Claude Code](/runtimes/claude-code) runtime pages for details.+`cost_usd` and `--session` detail are empty for Codex because Codex does not emit a cost signal or a conversation id on its usage metric. This is not a Beacon limitation. See the [Codex CLI](/runtimes/codex-cli#token-usage-and-cost) and [Claude Code](/runtimes/claude-code) runtime pages for details.## Examples@@ -85,7 +85,7 @@ Filters can be combined to narrow the report to a time range, model, agent harne| `--bucket <duration>` | Time-series bucket size, such as `1h` or `15m` || `--top <count>` | Limit each grouping to the top N entries. `0` keeps all entries |-## Runtime Log Selection+## Runtime log selectionBy default, the command reads the per-user endpoint runtime log. Use `--system` for a system-mode endpoint, or `--log-path` when reading a copied runtime log or a CI session artifact.diff --git a/docs/cli/version.mdx b/docs/cli/version.mdxindex 99f8aaca..cc8a0ecc 100644--- a/docs/cli/version.mdx+++ b/docs/cli/version.mdx@@ -3,7 +3,7 @@ title: "beacon version"description: "Display the Agent Beacon CLI version and check for updates"----## Command Overview+## Command overviewDisplay the version number, git commit, and build date of the Agent Beacon CLI, or check whether a newer released version is available.diff --git a/docs/cli/vscode.mdx b/docs/cli/vscode.mdxindex f845ea36..d4c37d07 100644--- a/docs/cli/vscode.mdx+++ b/docs/cli/vscode.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint integrations vscode"description: "Set up VS Code Copilot OpenTelemetry export for Beacon"----## Integration Command+## Integration commandVS Code Copilot Chat can export OpenTelemetry to Beacon's local collector. Beacon can configure VS Code user settings, show integration status, and validate whether VS Code-derived events are arriving in the runtime log.diff --git a/docs/cli/wazuh.mdx b/docs/cli/wazuh.mdxindex b59dbbf1..334472fe 100644--- a/docs/cli/wazuh.mdx+++ b/docs/cli/wazuh.mdx@@ -3,7 +3,7 @@ title: "beacon endpoint wazuh"description: "Configure Wazuh ingestion for Beacon endpoint events"----## Forwarding Command+## Forwarding commandBeacon writes Wazuh-compatible JSONL endpoint events to the local runtime log. The `beacon endpoint wazuh` commands help security and IT teams connect that log to Wazuh localfile ingestion, install Beacon-specific Wazuh rules, and write validation events.@@ -174,7 +174,7 @@ data.message: Beacon endpoint Wazuh validation event| `--system` | Use system endpoint paths and launch daemon || `--log-path <path>` | Runtime JSONL log path |-## Wazuh Dashboard fields+## Wazuh dashboard fieldsIn Wazuh Dashboard, Beacon event details appear under `data.*` fields. Useful columns include:diff --git a/docs/concepts/core-concepts.mdx b/docs/concepts/core-concepts.mdxindex 35d11ec1..b4d907d6 100644--- a/docs/concepts/core-concepts.mdx+++ b/docs/concepts/core-concepts.mdx@@ -19,27 +19,27 @@ Use this page as a quick reference for terms used across Asymptote and Agent Bea**Asymptote Managed** is the hosted Asymptote operating model for centralized ingest, retention, search, detections, fleet visibility, policy controls, identity mapping, approvals, SSO, RBAC, audit trails, and investigation workflows. See [Managed deployment](/deployment/managed).-## Private Deployment+## Private deployment**Private Deployment** applies managed capabilities with stronger infrastructure ownership, data isolation, residency, or custom retention requirements. See [Hosting Options](/deployment/hosting-options).-## Endpoint Agent+## Endpoint agentThe **endpoint agent** is the local Beacon service and configuration managed by `beacon endpoint`. It is Beacon's local collection path: it configures supported agent harnesses, runs the local collector, writes endpoint events to JSONL, and supports inspection, repair, dashboard, Wazuh, hooks, and forwarding commands.-## Runtime Surface+## Runtime surfaceA **runtime surface** is the telemetry interface exposed by an agent harness. Beacon supports different surfaces because each [agent harness](/runtimes) exposes activity differently, including local OpenTelemetry configuration, hook adapters, CI wrappers, cloud sandbox hooks, SDK instrumentation, admin-configured OpenTelemetry, and gateway-configured OTLP/HTTP export. See [Runtime Surface Overview](/runtimes).-## Agent Harness+## Agent harnessAn **agent harness** is the runtime or integration that produced an event. It can be a local coding agent, a CI job, a cloud-agent surface, an SDK-instrumented application, an admin-configured service integration, or a gateway-managed runtime surface. Examples include `claude`, `cline`, `codex`, `gemini_cli`, `grok`, `opencode`, `devin-cli`, `devin-desktop`, `factory`, `cursor`, `claude_cowork`, and `openclaw_gateway`. Beacon stores harness context in normalized events so investigators can filter by the source that generated the activity.-## CI Telemetry+## CI telemetry**CI telemetry** is agent runtime telemetry captured during ephemeral build jobs. Beacon can run a temporary collector through `beacon ci exec` or `beacon ci start` / `beacon ci finish`, write a completed `runtime.jsonl`, and export that file as an artifact or upload target. See [CI Telemetry Exports](/log-forwarding/ci-telemetry-exports).-## Cloud-Agent Telemetry+## Cloud-agent telemetry**Cloud-agent telemetry** is activity captured from provider-managed cloud agentsandboxes. Beacon cloud helpers print hook and storage setup so cloud sessions@@ -52,7 +52,7 @@ environment becomes available, so early bootstrap turns may precede telemetry.The **Observe SDK** is the `@asymptote/sdk` TypeScript package for instrumenting cloud-hosted agent applications, services, workers, serverless functions, and agent SDK integrations. It can export to Asymptote Managed hosted Observe or to a customer-managed OTLP collector. See [Asymptote Observe SDK](/sdk).-## Local Collector+## Local collectorThe **local collector** is Beacon's OpenTelemetry Collector pipeline on the endpoint. It receives OTLP from supported agent harnesses, batches and processes telemetry, writes normalized Beacon JSONL through the `beaconjson` exporter, and can optionally send collector signals to Splunk HEC or Falcon LogScale HEC.@@ -64,15 +64,15 @@ The **local collector** is Beacon's OpenTelemetry Collector pipeline on the endp**Hooks** are runtime-managed integration points that invoke Beacon's `beacon-hooks` adapter. Supported hook runtimes capture session, prompt, tool, command, approval, MCP-like, permission, and file edit events where those runtimes expose payloads.-## Endpoint Event+## Endpoint eventAn **endpoint event** is one normalized Beacon JSON object describing runtime activity. Endpoint events include a stable `event` action, endpoint context, harness context, severity, and any optional entities the source provides. CI and cloud telemetry paths use the same Beacon-compatible event model where their collection path emits normalized records. See [Endpoint event schema](/telemetry-schema/event-schema).-## Entity Model+## Entity modelThe **entity model** is Beacon's shared shape for runtime-specific payloads. Each event has an action plus typed context such as `endpoint`, `user`, `harness`, `origin`, `run`, `session`, `tool`, `file`, `command`, `mcp`, `approval`, `policy`, `prompt`, `content`, `gen_ai`, `destination`, and `health`. See [Telemetry fields](/telemetry-schema/fields).-## Threat Rules+## Threat rules**Threat rules** are local detection rules that match Beacon endpoint events and produce findings. Beacon's `scan` command runs the active rule corpus over local or CI JSONL without requiring hosted ingest. See [Detections](/detections).@@ -80,11 +80,11 @@ The **entity model** is Beacon's shared shape for runtime-specific payloads. Eac**Findings** are detection results produced when threat rules match runtime activity. They summarize the matched event, rule metadata, severity, and evidence so operators can review suspicious agent behavior in the local dashboard or downstream systems.-## Runtime JSONL Log+## Runtime JSONL logThe **runtime JSONL log** is Beacon's local audit log for endpoint collection. User-mode installs write to `~/.beacon/endpoint/logs/runtime.jsonl`; system-mode installs write to `/var/log/beacon-agent/runtime.jsonl`. Each line is a complete Beacon endpoint event. Beacon keeps that active `runtime.jsonl` path stable for dashboards and shippers, and rotates it at 10 MiB with five numbered local archives such as `runtime.jsonl.1`.-## Wazuh Localfile+## Wazuh localfile**Wazuh localfile** ingestion reads Beacon's runtime JSONL log from disk. Beacon can print localfile configuration, generate rule packs and sample events, and write validation events for Wazuh ingestion tests.@@ -96,43 +96,43 @@ The **runtime JSONL log** is Beacon's local audit log for endpoint collection. U**Falcon LogScale HEC** is CrowdStrike Falcon LogScale's HTTP Event Collector ingest path. Beacon can optionally configure a collector exporter that forwards normalized OTLP logs, traces, and metrics to a customer-managed Falcon LogScale HEC endpoint while preserving the local JSONL audit log.-## Elastic Content Pack+## Elastic content packThe **Elastic content pack** is Beacon's generated Filebeat, standalone Elastic Agent, Elasticsearch, and Kibana content for shipping local Beacon JSONL into Elastic. The pack reads the runtime log; Beacon itself does not store Elastic cluster URLs or credentials.-## Datadog Content Pack+## Datadog content packThe **Datadog content pack** is Beacon's generated Datadog Agent custom log collection content for shipping local Beacon JSONL into Datadog Logs. The pack reads the runtime log; Beacon itself does not store Datadog API keys or site configuration.-## Microsoft Sentinel Content Pack+## Microsoft Sentinel content packThe **Microsoft Sentinel content pack** is Beacon's generated Azure Monitor Agent and Log Analytics custom log content for shipping local Beacon JSONL into Microsoft Sentinel. The pack reads the runtime log; Beacon itself does not store Azure tenant IDs, client secrets, workspace IDs, DCR identifiers, or ingestion endpoints.-## AWS CloudWatch Logs Content Pack+## AWS CloudWatch Logs content packThe **AWS CloudWatch Logs content pack** is Beacon's generated Vector forwarding template, setup guidance, and sample events for shipping local Beacon JSONL into a customer-managed CloudWatch Logs log group. The pack reads the runtime log; Beacon itself does not store AWS credentials, IAM roles, log group retention, stream naming, or encryption settings.-## Sumo Logic Content Pack+## Sumo Logic content packThe **Sumo Logic content pack** is Beacon's generated setup guidance, upload smoke-test script, Vector forwarding template, and sample events for shipping local Beacon JSONL into a Sumo Logic Hosted Collector HTTP Logs & Metrics Source. The pack reads the runtime log; Beacon itself does not store Sumo Source URLs, tokens, or collector configuration.-## Rapid7 Content Pack+## Rapid7 content packThe **Rapid7 content pack** is Beacon's generated setup guidance, NDJSON upload smoke-test script, Vector forwarding template, and sample events for shipping local Beacon JSONL into a Rapid7 InsightIDR Custom Logs webhook event source. The pack reads the runtime log; Beacon itself does not store Rapid7 webhook URLs or tokens.-## AWS S3 Content Pack+## AWS S3 content packThe **AWS S3 content pack** is Beacon's generated setup guidance, AWS CLI smoke-test script, Vector `aws_s3` forwarding template, and sample events for shipping local Beacon JSONL into an S3 bucket. The current Vector path reads runtime and inventory JSONL and writes them below separate folders under one root prefix; Beacon itself does not store AWS credentials, bucket policies, lifecycle rules, or encryption settings.-## Google Cloud Storage Content Pack+## Google Cloud Storage content packThe **Google Cloud Storage content pack** is Beacon's generated setup guidance, GCS upload smoke-test script, Vector `gcp_cloud_storage` forwarding template, and sample events for shipping local Beacon JSONL into a GCS bucket. The current Vector path reads runtime and inventory JSONL and writes them below separate folders under one root prefix; Beacon itself does not store Google Cloud credentials, service accounts, bucket IAM, lifecycle rules, retention policies, or encryption settings.-## Vector Forwarding+## Vector forwarding**Vector forwarding** means a customer-managed Vector host agent tails Beacon's local JSONL streams, parses each JSON line, and delivers events to a downstream destination such as Sumo Logic, Rapid7 InsightIDR, Falcon LogScale, AWS CloudWatch Logs, AWS S3, or Google Cloud Storage. Vector owns checkpointing, batching, retries, credentials, and destination-specific settings.-## Customer-Managed Forwarding+## Customer-managed forwarding**Customer-managed forwarding** means an existing shipper, agent, Vector host agent, or SIEM pipeline reads Beacon's runtime JSONL log and routes each line to a downstream destination.@@ -140,15 +140,15 @@ The **Google Cloud Storage content pack** is Beacon's generated setup guidance,The **dashboard** is a loopback-only local view over Beacon runtime logs. It includes Log Search for investigating events, Detections and Findings for reviewing local threat-rule matches, and Security Overview for summarizing local activity, risk signals, harnesses, models, repositories, MCP servers, and runtime inventory without requiring a hosted Beacon account.-## Agent Runtime Inventory+## Agent runtime inventory**Agent Runtime Inventory** is Beacon's local view of configured, detected, and observed runtime coverage. It helps operators confirm which supported agent harnesses are present, which telemetry surfaces Beacon manages, which MCP servers are referenced by local configs, and which runtimes have recently produced events in the configured runtime log.-## Content Handling+## Content handling**Content handling** describes how Beacon treats supported prompt, command, attribute, and diff content before writing endpoint events. Beacon applies redaction, sanitization, truncation, and event-size limits before local storage or configured forwarding.-## User Mode And System Mode+## User mode and system mode**User mode** uses per-user paths under `~/.beacon/endpoint` and is the default for local evaluation. **System mode** uses root-managed paths under `/Library/Application Support/Beacon/Endpoint` and `/var/log/beacon-agent`, which is the preferred mode for packaged or MDM deployments.diff --git a/docs/concepts/faq.mdx b/docs/concepts/faq.mdxindex 3493134b..4cabbfff 100644--- a/docs/concepts/faq.mdx+++ b/docs/concepts/faq.mdx@@ -201,7 +201,7 @@ In a private or customer-managed design, the OTLP endpoint may instead point tocustomer-controlled collector or forwarding layer. The right target depends onthe deployment model, data-boundary requirements, and destination architecture.-### Does Managed require a customer-hosted management server?+### Does managed require a customer-hosted management server?Not necessarily. In Asymptote Managed, Asymptote operates the managed ingest andcontrol-plane services. For private deployments or stricter infrastructurediff --git a/docs/concepts/vector-forwarding.mdx b/docs/concepts/vector-forwarding.mdxindex f04843e5..5cd7daac 100644--- a/docs/concepts/vector-forwarding.mdx+++ b/docs/concepts/vector-forwarding.mdx@@ -30,7 +30,7 @@ sibling `inventory_state.jsonl`. Vector runs beside Beacon only when you chooseto forward those local streams into your own storage, SIEM, data lake, or logplatform.-## Open Source And Managed+## Open source and managedIn **Asymptote Open Source**, Agent Beacon is local-first. It configures supported agent harnesses, receives OTLP or hook telemetry, normalizes events, writes local runtime and inventory JSONL, and can generate forwarding content packs. Destination credentials, bucket policies, IAM roles, lifecycle rules, retention, encryption, and remote ingestion settings stay outside Beacon endpoint configuration.@@ -46,7 +46,7 @@ That is where Vector fits. For open-source deployments, Vector is an optional cuIn **Asymptote Managed**, the main path is different. Managed deployments use Asymptote-hosted ingest, retention, search, detections, governance, identity mapping, and investigation workflows. Vector is not the required managed-ingest architecture. You might still use a customer-managed Vector pipeline for an additional archive or downstream copy, but the core managed product provides the central pipeline and operational surface.-## Why The Handoff Is Local+## Why the handoff is localBeacon's local JSONL handoff keeps the endpoint posture simple and inspectable.The endpoint agent does not need object-storage credentials to keep collecting@@ -59,7 +59,7 @@ This also creates a clear ownership boundary:- Vector owns transport mechanics and destination delivery.- Your cloud, SIEM, or log platform owns remote access control, encryption, retention, indexing, and downstream detections.-## The Pipeline Shape+## The pipeline shapeMost Beacon Vector templates have the same shape:@@ -94,7 +94,7 @@ content_type = "application/x-ndjson"The source reads Beacon's local file. The transform replaces Vector's wrapper event with the parsed Beacon JSON object. The sink writes destination-ready records without changing Beacon's event schema.-## S3 In Depth+## S3 in depthAWS S3 forwarding is one example of how Beacon's local runtime and inventorystreams become durable object storage without Beacon storing AWS credentials.@@ -120,7 +120,7 @@ sudo /opt/beacon/bin/beacon endpoint s3 install-pack \The pack contains a `README.md`, `sample-event.jsonl`, an AWS CLI smoke-test script, and `vector.toml`. The generated config is a template for a customer-managed Vector host agent.-### File Source+### File sourceThe S3 template uses Vector's [`file` source](https://vector.dev/docs/reference/configuration/sources/file/) to tail the active Beacon log:@@ -135,7 +135,7 @@ read_from = "end"Vector stores file checkpoints below its global [`data_dir`](https://vector.dev/docs/reference/configuration/global-options/). Those checkpoints let Vector continue from the last observed file offset after restarts. The Vector process must be able to read `runtime.jsonl`, execute its parent directories, and write its `data_dir`.-### Remap Transform+### Remap transformThe source emits a Vector log event whose `.message` field contains the raw JSONL line. The [`remap` transform](https://vector.dev/docs/reference/configuration/transforms/remap/) uses Vector Remap Language to parse that message:@@ -152,7 +152,7 @@ source = '''The generated S3 pack also tails `inventory_state.jsonl` through a second source, transform, and S3 sink. Runtime events and inventory snapshots land under separate prefixes so operational inventory can be archived without mixing it into the runtime event stream.-### AWS S3 Sink+### AWS S3 sinkThe [`aws_s3` sink](https://vector.dev/docs/reference/configuration/sinks/aws_s3/) writes batches into your bucket:@@ -214,7 +214,7 @@ For a dedicated Beacon prefix, least privilege usually starts with `s3:PutObjectAdd `s3:PutObjectTagging`, KMS permissions, bucket-owner controls, or condition keys only when your AWS environment requires them. Bucket lifecycle, retention, server-side encryption, replication, access logs, and object lock should be configured in AWS, not in Beacon.-## GCS Authentication On macOS+## GCS authentication on macOSThe packaged GCS flow mirrors the S3 runtime/inventory layout with`gcp_cloud_storage` sinks and a root `BEACON_GCS_PREFIX`. The signed package@@ -257,7 +257,7 @@ vendor=beacon product=endpoint-agent destination.type=s3 destination.mode=aws_s3If events do not appear, check the same ownership boundary in order: Beacon should be writing the local runtime log, Vector should be reading the same path and writing checkpoints, the Vector service should have AWS credentials available, and the bucket policy should allow object creation for the selected prefix.-## Broader Integrations+## Broader integrationsThe same Vector pattern powers several Beacon content packs:@@ -268,11 +268,11 @@ The same Vector pattern powers several Beacon content packs:Other customer-managed pipelines can use the same contract even when they do not use Vector: read the active Beacon JSONL log, checkpoint offsets, follow rotation, preserve each line as one event, retry transient failures, and keep destination secrets outside Beacon endpoint configuration.-## Content Handling+## Content handlingBeacon applies redaction, sanitization, truncation, and event-size limits before endpoint events reach `runtime.jsonl`. Vector forwards what Beacon wrote. Review Beacon content settings, Vector service permissions, bucket or SIEM access, downstream retention, and object lifecycle policies together so retained telemetry matches your approved collection policy.-## Vector References+## Vector referencesUse the official Vector docs when adapting generated templates:diff --git a/docs/contributing/beacon-sandbox.mdx b/docs/contributing/beacon-sandbox.mdxindex 5728646f..8ddf27e9 100644--- a/docs/contributing/beacon-sandbox.mdx+++ b/docs/contributing/beacon-sandbox.mdx@@ -1,5 +1,5 @@----title: "Testing Beacon In A Sandbox"+title: "Testing Beacon in a Sandbox"description: "Run a real AI coding session in a throwaway Linux or Windows machine and check that Beacon recorded it"---@@ -7,7 +7,7 @@ description: "Run a real AI coding session in a throwaway Linux or Windows machi`beacon-sandbox` is a testing tool for Beacon contributors. It starts a throwaway machine, installs your local Beacon build on it, runs a real Claude Code session inside it, and then checks whether Beacon recorded what the agent actually did.-You would use it when you have changed something about how Beacon captures telemetry and you want proof that it still works against a live agent — not just that the unit tests pass.+Use it when you have changed something about how Beacon captures telemetry and you want proof that it still works against a live agent, not just that the unit tests pass.Nothing runs on your own machine, so your local Beacon setup is untouched, and the machine is destroyed when the test finishes.@@ -17,20 +17,17 @@ It runs on two platforms, and where the throwaway machine comes from is the only|---|---|---|| Linux | A Modal sandbox, rented per test | A Modal account and an Anthropic API key || Windows | A GitHub-hosted runner, which is already disposable | Write access to this repository and an Anthropic API key |-| macOS | — | Not possible; neither backend offers macOS. See [Limitations](#limitations) |+| macOS | None | Not possible. Neither backend offers macOS. See [Limitations](#limitations) |-Everything after that is shared — the same scenario files, the same checks, the same verdicts, the same-`verify` and `--mutate` commands. Most of this page applies to both. If you are working on Windows,-read [Testing The Windows Build](#testing-the-windows-build) for the parts that differ, and skip the-Modal setup below.+Everything after that is shared: the same scenario files, the same checks, the same verdicts, and the same `verify` and `--mutate` commands. Most of this page applies to both. If you are working on Windows, read [Testing the Windows build](#testing-the-windows-build) for the parts that differ, and skip the Modal setup below.<Note>- This is a tool for working *on* Beacon. It is not part of Beacon itself, it is not included in any release, and installing Beacon does not install this. Beacon's own telemetry collection stays local and offline as always.+ This is a tool for working on Beacon. It is not part of Beacon itself, it is not included in any release, and installing Beacon does not install it. Beacon's own telemetry collection stays local and offline as always.</Note>-## Why A Sandbox Instead Of Unit Tests+## Why a sandbox instead of unit tests-Beacon's unit tests feed it example telemetry and check the output. That catches a lot, but it cannot answer the question that matters most: *when a real agent runs a real command, does Beacon record it?*+Beacon's unit tests feed it example telemetry and check the output. That catches a lot, but it cannot answer the question that matters most: when a real agent runs a real command, does Beacon record it?Real agents produce messier telemetry than any handwritten example. A field can quietly stop being filled in, and every unit test still passes because none of them ever saw what the live agent actually sends.@@ -39,14 +36,13 @@ The catch is that AI sessions are not repeatable. Ask an agent to run a commandThe tool works around this with markers rather than exact comparison:- Each test puts a **random one-off string** into the prompt, then checks that string appears in Beacon's log. Since the tool invented the string, a match cannot be coincidence.-- The agent is also asked to **write that string into a file**. If the file is there, the agent definitely did the work — so if Beacon has no record of it, that is Beacon's problem and not the model having a lazy day.+- The agent is also asked to **write that string into a file**. If the file is there, the agent did the work, so a missing record is Beacon's problem rather than the model having a lazy day.That second part is what makes the results trustworthy. Without it, "Beacon missed the event" and "the agent never ran the command" look exactly the same.-## Before You Start+## Before you start-This section covers the **Linux** backend. Testing the Windows build needs neither a Modal account nor-any of the setup below — see [Setting It Up](#setting-it-up) in the Windows section instead.+This section covers the **Linux** backend. Testing the Windows build needs neither a Modal account nor any of the setup below. See [Setting it up](#setting-it-up) in the Windows section instead.You need two accounts, and neither can be set up for you:@@ -98,7 +94,7 @@ If something is missing, `doctor` prints the fix beside it. Run the fix, then ru`doctor` is worth running any time a test behaves strangely. Most confusing failures turn out to be a missing or outdated build artifact, and it will tell you.</Note>-### Keeping Your API Key Out Of Your Shell+### Keeping your API key out of your shellThree ways to supply the key, in the order the tool looks for them:@@ -114,7 +110,7 @@ To create the Modal secret: `modal secret create my-anthropic-key ANTHROPIC_API_The Modal secret option keeps the key furthest from your machine, but it comes with one small trade-off: because the tool never sees the key itself, it cannot double-check that the key never leaked into the collected logs. It will say so in the results rather than quietly skipping that check.</Note>-## Your First Test+## Your first testBuild Beacon for Linux, then run a single test:@@ -140,7 +136,7 @@ This takes about three minutes and costs a few cents. You will see the sandbox s`PASS` means Beacon recorded everything this test looked for.-## Understanding The Results+## Understanding the resultsEvery test ends in one of three states:@@ -148,7 +144,7 @@ Every test ends in one of three states:|--------|---------|------------|| **PASS** | Beacon recorded what the test looked for | Nothing || **FAIL** | Something the test expected is missing or empty | Read the failure detail below |-| **INCONCLUSIVE** | The agent never did the requested work, so there was nothing to record | Run it again — this is not a Beacon problem |+| **INCONCLUSIVE** | The agent never did the requested work, so there was nothing to record | Run it again. This is not a Beacon problem |A `FAIL` tells you which expectation broke and why that expectation exists:@@ -162,11 +158,11 @@ FAIL s02-bash-commandrules cannot fire.```-Read it from the top. The agent demonstrably did the work, so the missing event is a real gap. The event counts then hint at where it went — seven events landed under a different name, which points at a labelling problem rather than a dropped event.+Read it from the top. The agent demonstrably did the work, so the missing event is a real gap. The event counts hint at where it went: seven events landed under a different name, which points at a labelling problem rather than a dropped event.-### Warnings Mean "Could Not Check"+### Warnings mean "could not check"-Alongside pass and fail, you may see `[WARN]` lines. These are not failures, but they are not clean results either — each one means a check could not run:+Alongside pass and fail, you may see `[WARN]` lines. These are not failures, but they are not clean results either. Each one means a check could not run:| Warning | What it means ||---------|---------------|@@ -177,22 +173,21 @@ Alongside pass and fail, you may see `[WARN]` lines. These are not failures, butIf you are reporting results to someone else, mention these. Silence from this tool is meant to mean "checked and clean", so a warning is worth passing on.-### A Failure Is Not Always A Beacon Bug+### A failure is not always a Beacon bug-Tests encode what Beacon *should* do. When Beacon's behaviour legitimately improves, an old expectation can become out of date and start failing. Before concluding you have found a bug:+Tests encode what Beacon should do. When Beacon's behaviour legitimately improves, an old expectation can go out of date and start failing. Before concluding you have found a bug:1. Read the failing expectation's `why` and compare it against the event counts in the output. Did the event move somewhere else rather than disappear?-2. If your change touched `collector-builder/`, check that you rebuilt it — see the warning below.+2. If your change touched `collector-builder/`, check that you rebuilt it. See the warning below.3. Only then treat it as a gap in Beacon.<Warning>**If your change is in `collector-builder/`, rebuild it before testing.** Telemetry processing lives in a separate binary from the `beacon` command, so a test run will happily use an older copy and pass without ever exercising your change. `doctor` warns about this, and it is the single most common way to waste a test run.</Warning>-## The Tests You Can Run+## The tests you can run-These run on the Linux backend. The Windows ones are listed in-[Testing The Windows Build](#running-one).+These run on the Linux backend. The Windows ones are listed in [Testing the Windows build](#running-one).```bashgo run ./cmd/beacon-sandbox run --scenario s01-hello # one test@@ -213,16 +208,9 @@ go run ./cmd/beacon-sandbox run # all of them, ~30 minUse one test while you are iterating. Run all of them before opening a pull request.-The `s0*` tests collect through a temporary collector — the path Beacon uses in CI and cloud agents.-The `i0*` tests install Beacon properly first, so they cover things the others cannot: whether config-lands where Beacon says it did, whether the service actually starts, and whether a permanently-installed collector receives telemetry.+The `s0*` tests collect through a temporary collector, the path Beacon uses in CI and cloud agents. The `i0*` tests install Beacon properly first, so they cover things the others cannot: whether config lands where Beacon says it did, whether the service actually starts, and whether a permanently installed collector receives telemetry.-`i02` is the slowest test by some margin, and the reason is worth knowing. A system-mode install on-Linux is managed by systemd, and systemd only runs as process 1 — but Modal's own startup process-holds that slot, so systemd refuses to start. The way around it is a privileged container inside the-sandbox, where systemd *is* process 1, and running the whole test in there. The tool sets this up for-you when a test asks for it:+`i02` is the slowest test by some margin, and the reason is worth knowing. A system-mode install on Linux is managed by systemd, and systemd only runs as process 1, but Modal's own startup process holds that slot, so systemd refuses to start. The way around it is a privileged container inside the sandbox, where systemd is process 1, with the whole test running in there. The tool sets this up when a test asks for it:```yaml title="Asking for a real systemd"install:@@ -233,53 +221,39 @@ install:expect_service_kind: systemd```-`expect_service_kind` is not redundant with `expect_status_running`. Beacon falls back to a plain-background collector when it finds no service manager, and that fallback also reports itself as-running — so without naming the backend you expect, a test meant to cover systemd could quietly pass-while covering the fallback instead.+`expect_service_kind` is not redundant with `expect_status_running`. Beacon falls back to a plain background collector when it finds no service manager, and that fallback also reports itself as running. Without naming the backend you expect, a test meant to cover systemd could quietly pass while covering the fallback instead.-## Testing The Windows Build+## Testing the Windows build-Modal offers Linux machines only, so Windows needs a different disposable machine. It uses a-GitHub-hosted Windows runner, which is already one: a fresh virtual machine per job, with-administrator rights, UAC disabled, and a real Service Control Manager — everything an endpoint-install needs.+Modal offers Linux machines only, so Windows needs a different disposable machine. It uses a GitHub-hosted Windows runner, which is already one: a fresh virtual machine per job, with administrator rights, UAC disabled, and a real Service Control Manager. That is everything an endpoint install needs.-The difference from the Linux path is where the sandbox is. On Modal the tool starts a machine and-drives it from outside. On Windows **the runner is the sandbox**, and the tool runs inside it. The-collected output is uploaded and judged on your machine afterwards by the same code that judges a-Modal run, so a Windows verdict is produced by the same rules as a Linux one.+The difference from the Linux path is where the sandbox is. On Modal the tool starts a machine and drives it from outside. On Windows **the runner is the sandbox**, and the tool runs inside it. The collected output is uploaded and judged on your machine afterwards by the same code that judges a Modal run, so a Windows verdict comes from the same rules as a Linux one.Runner minutes are free on this public repository, so unlike the Linux tests these cost only theAnthropic API session.-### Running One+### Running one```bash title="Dispatch a Windows test"gh workflow run windows-sandbox.yml -f scenario=w03-hook-capturegh run watch```-Leave `scenario` empty to run every Windows test. Each takes a few minutes; the whole set is about-fifteen.+Leave `scenario` empty to run every Windows test. Each takes a few minutes, and the whole set takes about fifteen.| Test | Covers ||------|--------|-| `w00-probe` | The `beacon ci exec` collection path. Known to be unreliable on Windows — see [#320](https://github.com/asymptote-labs/agent-beacon/issues/320) |+| `w00-probe` | The `beacon ci exec` collection path. Known to be unreliable on Windows. See [#320](https://github.com/asymptote-labs/agent-beacon/issues/320) || `w01-install-service` | A system-mode install registered with the Service Control Manager, then a session against it || `w02-install-supervised` | A user-mode install, which falls back to a supervised collector because Windows has no per-user service manager || `w03-hook-capture` | Capture through *installed* hooks: prompts, command text, and file edits || `w04-denied-tool` | Approvals and denials through installed hooks |-`w03` is the one that matters most. It goes through hooks Beacon installed rather than a temporary-collector, which is what a real user gets — and it is the only test that can tell you the command-string Beacon writes into a runtime's settings is one that runtime can actually execute.+`w03` is the one that matters most. It goes through hooks Beacon installed rather than a temporary collector, which is what a real user gets. It is also the only test that can confirm the command string Beacon writes into a runtime's settings is one that runtime can execute.-### Setting It Up+### Setting it up-Dispatching needs write access to the repository, plus an `ANTHROPIC_API_KEY` secret in the-`windows-sandbox` environment. Scoped to an environment rather than the repository, matching how the-release secrets are handled:+Dispatching needs write access to the repository, plus an `ANTHROPIC_API_KEY` secret in the `windows-sandbox` environment. It is scoped to an environment rather than the repository, matching how the release secrets are handled:```bash title="Store the key, without it entering your shell history"gh api -X PUT repos/asymptote-labs/agent-beacon/environments/windows-sandbox@@ -287,26 +261,17 @@ printf '%s' "$ANTHROPIC_API_KEY" | gh secret set ANTHROPIC_API_KEY \--repo asymptote-labs/agent-beacon --env windows-sandbox```-Use a dedicated, budget-capped key. The harness runs a real agent with-`--dangerously-skip-permissions`, and the per-session budget in a scenario is a client-side cap-rather than an account guard.+Use a dedicated, budget-capped key. The harness runs a real agent with `--dangerously-skip-permissions`, and the per-session budget in a scenario is a client-side cap rather than an account guard.<Note>- The workflow is `workflow_dispatch` only, and deliberately. It needs an API key to run a real- session, and on a public repository that secret must never be reachable from a fork's pull request —- so there is no `pull_request` trigger and there must never be a `pull_request_target` one.+ The workflow is `workflow_dispatch` only, deliberately. It needs an API key to run a real session, and on a public repository that secret must never be reachable from a fork's pull request. So there is no `pull_request` trigger, and there must never be a `pull_request_target` one.</Note>-### One Check Works Differently There+### One check works differently there-Every Linux run fingerprints your own Beacon state before and after, so a test that accidentally-installed something on your machine is caught rather than assumed impossible. That comparison only-means something when the sandbox is a *different* machine.+Every Linux run fingerprints your own Beacon state before and after, so a test that accidentally installed something on your machine is caught rather than assumed impossible. That comparison only means something when the sandbox is a different machine.-On Windows it is not — the install being tested is itself the change the guard would report. So the-run records a different kind of evidence: that the machine is disposable (a GitHub-hosted runner, one-fresh VM per job). The verdict says which of the two it relied on rather than silently reporting the-comparison as clean:+On Windows it is not, because the install being tested is itself the change the guard would report. The run records a different kind of evidence instead: that the machine is disposable, a GitHub-hosted runner with one fresh VM per job. The verdict says which of the two it relied on rather than silently reporting the comparison as clean:```[WARN] safety.host_untouched: host isolation was not verified by comparison because the guest@@ -315,8 +280,7 @@ comparison as clean:(github-hosted ephemeral runner (fresh VM per job))```-That warning is expected on every Windows run. It is not a problem to fix; it is the tool declining to-claim a check it could not perform.+That warning is expected on every Windows run. It is not a problem to fix. It is the tool declining to claim a check it could not perform.## Commands@@ -330,7 +294,7 @@ claim a check it could not perform.`verify` is worth knowing about. Every run saves its output under `runs/`, and `verify` re-checks that saved output without starting a sandbox or calling the API. If you are adjusting what a test expects, use `verify` rather than paying for another run.-## Writing Your Own Test+## Writing your own testTests are YAML files in `beacon-sandbox/scenarios/`:@@ -349,7 +313,7 @@ expect:- `{{canary}}` becomes the random one-off string for that run. `{{sentinel}}` and `{{workdir}}` are also substituted.- `sentinel` is the file the agent must leave behind. It has to contain the canary, so a file created by setup does not count.-- `why` is required on every expectation — a failure nobody can interpret is not useful.+- `why` is required on every expectation, because a failure nobody can interpret is not useful.- `optional: true` records an expectation without failing the run, for something known to be missing.Check your file without spending anything:@@ -358,7 +322,7 @@ Check your file without spending anything:go test ./scenario/```-## Checking That The Checks Work+## Checking that the checks workA test that cannot fail is worse than no test, so you can deliberately damage a saved run and confirm the tool notices:@@ -375,9 +339,7 @@ go test ./...## Limitations<Warning>- **The macOS build cannot be tested this way.** Modal provides Linux machines, and the Windows path- above uses a GitHub-hosted Windows runner; neither offers macOS. Anything macOS-specific — launchd,- the signed installer, notarization — is out of reach and has to be checked by hand on a Mac.+ **The macOS build cannot be tested this way.** Modal provides Linux machines, and the Windows path above uses a GitHub-hosted Windows runner. Neither offers macOS, so anything macOS-specific (launchd, the signed installer, notarization) has to be checked by hand on a Mac.</Warning>- **The systemd tests run nested.** `i02` runs inside a container within the sandbox, so it is slower and needs a few more minutes of patience than the others.diff --git a/docs/deployment/managed.mdx b/docs/deployment/managed.mdxindex fb04e2f6..b1c81121 100644--- a/docs/deployment/managed.mdx+++ b/docs/deployment/managed.mdx@@ -8,7 +8,7 @@ Asymptote Managed builds on the open-source Agent Beacon foundation for teams thUse this path when local JSONL and customer-managed forwarding are not enough on their own, or when agent adoption has moved beyond a small local pilot.-## What Managed Adds+## What managed addsAsymptote Managed includes the open-source capture and forwarding paths, then adds the managed services needed to operate agent security at company scale.@@ -21,9 +21,9 @@ Asymptote Managed includes the open-source capture and forwarding paths, then ad| Access control | SSO, role-based access control, and audit trails || Operations support | Priority support, onboarding, and rollout guidance |-## Core Managed Workflows+## Core managed workflows-### Centralize Runtime Visibility+### Centralize runtime visibilityManaged ingest turns endpoint and cloud-agent telemetry into searchable fleet-wide visibility. Security teams can review which agents are running, which tools they use, and what sensitive files or data are involved in agent activity.@@ -33,19 +33,19 @@ variables. Asymptote can operate the secure ingest and retention layer for you,or work with your team on a production-grade forwarding design incustomer-managed infrastructure.-### Govern Agent Activity+### Govern agent activityPolicy, identity mapping, and approvals help teams connect runtime actions back to users and workflows. Use this when you need governance beyond a local audit log or SIEM-forwarded event stream.-### Investigate Agent Behavior+### Investigate agent behaviorInvestigation timelines and case workflows organize prompts, tool calls, file access, command execution, and related context so security teams can reconstruct what happened during an agent session.-### Support Enterprise Rollout+### Support enterprise rolloutManaged deployments include rollout planning, onboarding, and support for teams deploying across endpoints and execution environments.-## Private Deployment+## Private deploymentFor regulated teams that need dedicated infrastructure or stricter data boundaries, Asymptote supports private cloud or customer-controlled deployment options.@@ -56,7 +56,7 @@ Private deployment can include:- coverage across endpoints and execution environments- dedicated deployment engineering and rollout planning-## Get Access+## Get accessRequest access or discuss deployment requirements at [asymptotelabs.ai/contact](https://asymptotelabs.ai/contact). For plan details, see [Asymptote pricing](https://asymptotelabs.ai/pricing).diff --git a/docs/deployment/open-source.mdx b/docs/deployment/open-source.mdxindex 07f7e969..f43fe151 100644--- a/docs/deployment/open-source.mdx+++ b/docs/deployment/open-source.mdx@@ -57,7 +57,7 @@ beacon endpoint install --harness claude,codex,gemini```<Note>- System-mode install (`--system`) is supported on macOS and on Linux distributions that use systemd. The default mode uses per-user paths; use `--system` as root for package or MDM deployments. On Linux, installing the `.deb` or `.rpm` does the system install for you — see [Linux](/platforms/linux).+ System-mode install (`--system`) is supported on macOS and on Linux distributions that use systemd. The default mode uses per-user paths; use `--system` as root for package or MDM deployments. On Linux, installing the `.deb` or `.rpm` does the system install for you. See [Linux](/platforms/linux).</Note>Beacon records supported prompt, tool, command, file, approval, policy, and runtime context when the source runtime emits it. Before events are written to `runtime.jsonl` or sent through configured destinations, Beacon applies redaction, sanitization, truncation, and event-size limits.diff --git a/docs/detections/engine.mdx b/docs/detections/engine.mdxindex bceee589..08250b80 100644--- a/docs/detections/engine.mdx+++ b/docs/detections/engine.mdx@@ -3,13 +3,13 @@ title: "Detection Engine"description: "How Beacon loads, validates, evaluates, and reports detections"----## Engine Overview+## Engine overviewThe Beacon detection engine runs threat rules over ordered endpoint events. The engine ships in the Beacon CLI, while the rule corpus is external data loaded from a directory, the local rule store, or a small embedded baseline.Local scanning is read-only and does not contact the network.-## Active Rule Resolution+## Active rule resolutionWhen `beacon scan` runs, Beacon resolves the active rules in this order:@@ -19,7 +19,7 @@ When `beacon scan` runs, Beacon resolves the active rules in this order:The per-user store is under the endpoint base directory, commonly `~/.beacon/endpoint/rules`. System-mode installs use the system endpoint base directory.-## Load-Time Validation+## Load-time validationRules are checked before any event scanning begins.@@ -36,7 +36,7 @@ Beacon:Invalid rules fail early so scans do not produce ambiguous results.-## Event Input+## Event input`beacon scan` reads the resolved `runtime.jsonl` endpoint log unless a different path is supplied with `--log-path`.@@ -44,7 +44,7 @@ Each line is parsed as a Beacon endpoint event. The scan keeps the ordered eventUse `--session` to scan only events whose `session.id` contains a given value.-## Single-Event Matching+## Single-event matchingA single-event rule has a top-level `match` expression. The engine evaluates that expression independently against each event.@@ -56,7 +56,7 @@ match: >If any event satisfies the expression, the rule produces a finding with that event as evidence.-## Correlation Matching+## Correlation matchingA correlation rule describes ordered steps inside a session window.@@ -81,7 +81,7 @@ Correlation is useful when no single event is suspicious enough on its own, but"In order" means the order the events happened, not the order they were written. `beaconscan` sorts the runtime log by `(timestamp, sequence)` before evaluating, because append-order is not emission order — a hook writes the moment it intercepts a tool call, while the+order is not emission order. A hook writes the moment it intercepts a tool call, while thecollector exporter writes on its export interval. See [eventordering](/telemetry-schema/event-schema#event-ordering).@@ -98,7 +98,7 @@ When a rule fires, Beacon emits a finding. Findings include:Human output summarizes findings by severity, rule, session, reason, and evidence lines. JSON output emits machine-readable finding objects for automation.-## Filtering And Gates+## Filtering and gates`beacon scan` supports two severity controls:@@ -107,7 +107,7 @@ Human output summarizes findings by severity, rule, session, reason, and evidencThe fail gate is evaluated before display filtering, so automation can fail on all matching detections even when output is narrowed for readability.-## Operational Boundaries+## Operational boundariesScanning does not mutate endpoint telemetry, change rule files, or fetch remote content. Rule installation and remote rule pack retrieval are explicit `beacon rules` workflows.diff --git a/docs/detections/index.mdx b/docs/detections/index.mdxindex 261eb3ad..b476dd9f 100644--- a/docs/detections/index.mdx+++ b/docs/detections/index.mdx@@ -47,7 +47,7 @@ Run a high-severity gate, useful in local validation or CI-like checks:beacon scan --fail-on high```-## What Detections Look For+## What detections look forDetections focus on risky agent behavior that is hard to understand from one raw log line alone:@@ -64,7 +64,7 @@ Because rules run over the shared Beacon event model, the same rule vocabulary c[Inventory](/guides/inventory) helps explain which harnesses, local config, MCP servers, and skills are present and observable on an endpoint. Detection coverage depends on the telemetry fields emitted by those supported harnesses and visible local configuration.-## Detection Coverage+## Detection coverageBeacon ships with a small built-in baseline so `beacon scan` works before any rule store is installed. The broader rule pack is distributed as a release asset and includes categories like these:@@ -82,7 +82,7 @@ Beacon ships with a small built-in baseline so `beacon scan` works before any ruRules only evaluate events that exist in the runtime log. For example, an MCP detection needs MCP-like activity to be emitted by a supported harness, and a prompt-injection rule needs retained prompt or content fields to be present under the endpoint's local data-retention settings.-## Detection Flow+## Detection flow1. A supported agent harness emits runtime telemetry.2. Beacon normalizes that telemetry into endpoint events and writes `runtime.jsonl`.@@ -93,7 +93,7 @@ Rules only evaluate events that exist in the runtime log. For example, an MCP deYou can run the same local detection flow from the command line with [`beacon scan`](/cli/scan) or inspect it in the loopback-only [endpoint dashboard](/cli/dashboard). The dashboard Detections view lists active rules, while the Findings view runs those rules over the configured runtime log on demand.-## Rules And Findings+## Rules and findingsA rule is the durable detection definition. It contains an `id`, `title`, `severity`, CEL logic, and test fixtures that prove the expected behavior.@@ -147,7 +147,7 @@ tests:command: { command: "ls -la" }```-## Rule Sources+## Rule sourcesBeacon can run detections from three sources, resolved in this order:@@ -169,7 +169,7 @@ beacon rules add ./rulesThe per-user store is under the endpoint base directory, commonly `~/.beacon/endpoint/rules`. System-mode installs use the system endpoint base directory.-## Author And Validate Rules+## Author and validate rulesThreat rules are meant to be reviewed and tested like code. A new rule should start as `experimental`, include a plain-language `emit.reason`, and carry at least one fixture that proves the expected verdict.@@ -187,7 +187,7 @@ beacon rules fieldsUse the [Detection YAML Schema](/detections/yaml-schema) page for the rule document shape, the [Detection Standard](/detections/standard) page for maturity and conformance requirements, and the [Detection Engine](/detections/engine) page for load-time validation and evaluation behavior.-## Operational Notes+## Operational notes- `beacon scan --min-severity <level>` filters displayed findings.- `beacon scan --fail-on <level>` exits non-zero when any finding at or above the threshold exists.@@ -196,13 +196,13 @@ Use the [Detection YAML Schema](/detections/yaml-schema) page for the rule docum- `beacon rules pull` is the only rules workflow that reaches the network, and only for the explicit URL you provide.- The local dashboard mirrors `beacon scan` rule resolution and finding behavior, but stays loopback-only and read-only.-## Managed Detections+## Managed detectionsThe open-source Beacon flow runs detections locally over endpoint JSONL. [Asymptote Managed](/deployment/managed) builds on the same telemetry foundation with centralized ingest, retention, search, detections, fleet-wide visibility, policy workflows, identity mapping, SSO/RBAC, and investigation workflows.Use local Beacon detections when you need offline endpoint checks or customer-controlled forwarding. Use Managed when you need centralized review across a fleet or organization.-## Read Next+## Read next<Columns cols={2}><Card title="YAML Schema" icon="code" href="/detections/yaml-schema">diff --git a/docs/detections/standard.mdx b/docs/detections/standard.mdxindex 8e15871b..aaa41fb3 100644--- a/docs/detections/standard.mdx+++ b/docs/detections/standard.mdx@@ -3,7 +3,7 @@ title: "Detection Standard"description: "The threat-rules/v1 standard for portable AI-agent security detections"----## Standard Overview+## Standard overviewBeacon threat rules are an open detection-rule format for AI-agent security threats. The standard is intentionally small: rules are YAML, match logic is CEL, input data is the Beacon endpoint event schema, and every rule carries fixtures that prove its expected behavior.@@ -15,7 +15,7 @@ The current rule format is `threat-rules/v1`.The version covers the rule document shape, required metadata, CEL contract, correlation model, and fixture semantics. Rule files also include their own integer `version` field, which is the content revision for that individual rule.-## Design Goals+## Design goalsThe standard is designed to be:@@ -25,7 +25,7 @@ The standard is designed to be:- testable without a live endpoint- portable across engines that implement the same conformance checks-## CEL Contract+## CEL contractRules express detection logic in CEL. The current event is bound as `e`.@@ -43,7 +43,7 @@ The CEL contract has a few important requirements:- Regular expressions use RE2 semantics through CEL `.matches(...)`.- Invalid CEL is rejected when the rule loads, before scanning begins.-## Maturity Ladder+## Maturity ladderThe `status` field communicates how much evidence supports a rule.@@ -55,7 +55,7 @@ The `status` field communicates how much evidence supports a rule.Use `experimental` for new or narrow rules that need field testing. Use `stable` when the rule has both positive and negative examples and is suitable for a shared corpus.-## Verdict Model+## Verdict modelRule evaluation produces one of two verdicts:@@ -64,7 +64,7 @@ Rule evaluation produces one of two verdicts:Fixtures are the conformance boundary. A rule says what should happen, and an engine proves it by running each fixture and comparing the actual verdict to the declared one.-## Severity And Posture+## Severity and posture`severity` describes the importance of a finding when the rule fires. It uses the same severity values as Beacon endpoint events: `info`, `low`, `medium`, `high`, and `critical`.@@ -87,7 +87,7 @@ taxonomy:Use taxonomy fields to make a rule easier to map into security programs, not as part of detection logic.-## Publishable Rule Checklist+## Publishable rule checklistA publishable rule should:diff --git a/docs/detections/yaml-schema.mdx b/docs/detections/yaml-schema.mdxindex 0ea0142b..4c940d62 100644--- a/docs/detections/yaml-schema.mdx+++ b/docs/detections/yaml-schema.mdx@@ -3,13 +3,13 @@ title: "Detection YAML Schema"description: "Human-readable reference for Beacon threat-rule YAML files"----## Schema Overview+## Schema overviewBeacon detection rules are YAML documents ending in `.rule.yaml`. Each rule describes one security condition over Beacon endpoint events and includes enough metadata and tests for the rule to be validated before it runs.The structural schema is the `threat-rules/v1` JSON Schema in the Agent Beacon repository. The runtime engine also compiles CEL expressions and checks rule fixtures, because those checks cannot be fully represented by JSON Schema alone.-## Minimal Rule+## Minimal ruleA rule must define its identity, maturity, detection logic, emitted reason, and at least one fixture.@@ -33,7 +33,7 @@ tests:command: { command: "curl https://example.com" }```-## Top-Level Fields+## Top-level fields| Field | Required | Meaning || --- | --- | --- |@@ -52,7 +52,7 @@ tests:Exactly one of `match` or `correlation` must be present.-## Match Rules+## Match rulesA `match` rule evaluates one event at a time. The event is available as `e`, and field paths mirror the endpoint event JSON shape.@@ -64,7 +64,7 @@ match: >Use `match` when one event is enough to explain the behavior, such as a command, file read, approval decision, or MCP tool call.-## Correlation Rules+## Correlation rulesA `correlation` rule evaluates an ordered sequence of events. In `threat-rules/v1`, correlations are scoped to a single session and must complete inside a duration window.@@ -112,7 +112,7 @@ tests:Fixtures keep rules reviewable. They show what the author intended to detect and what should stay out of scope.-## Field Paths+## Field pathsCEL expressions use `e.<field>` paths that match the Beacon event schema. Common paths include:diff --git a/docs/docs.json b/docs/docs.jsonindex f67ef078..ca7632ba 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -270,6 +270,13 @@}]},+ {+ "group": "Support",+ "icon": "life-ring",+ "pages": [+ "support/troubleshooting"+ ]+ },{"group": "Contributing","icon": "code-branch",@@ -402,7 +409,14 @@"cli/rules-fields"]},- "cli/scan",+ {+ "group": "beacon scan",+ "root": "cli/scan",+ "pages": [+ "cli/scan-local",+ "cli/scan-ci-gates"+ ]+ },"cli/token-usage","cli/version"]@@ -453,7 +467,8 @@"icon": "clipboard-list","root": "guides/use-cases","pages": [- "guides/agent-runtime-telemetry"+ "guides/agent-runtime-telemetry",+ "guides/inventory"]},{diff --git a/docs/get-started/overview.mdx b/docs/get-started/overview.mdxindex b8ec3a0a..06534465 100644--- a/docs/get-started/overview.mdx+++ b/docs/get-started/overview.mdx@@ -7,31 +7,31 @@ Asymptote helps security and IT teams understand what AI agents are doing at runYou can start with open-source telemetry across the agent surfaces you already run, then move into centralized visibility, policy controls, and investigations when a small pilot turns into a broader rollout.-## Why Teams Need This+## Why teams need thisAI agents create a visibility gap that most security tools do not cover well. Traditional endpoint and application logs can usually tell you that something happened, but not enough about the agent session that caused it.In practice, teams usually run into a few problems:-### Unknown Agents, Unknown Risk+### Unknown agents, unknown risk- Teams often do not have a reliable inventory of which agent tools are in use.- Ownership is unclear once agents spread across individual laptops and teams.- It becomes hard to answer basic questions such as which harness is running, what it can access, and where activity should be monitored.-### Runtime Moves Faster Than Review+### Runtime moves faster than review- Agents can read files, call tools, write code, and trigger actions very quickly.- Manual review works for a small pilot, but it does not scale once many users or teams depend on agents.- Security teams need a way to observe and govern activity while it is happening, not only after the fact.-### Logs Without Runtime Context+### Logs without runtime context- Standard logs may show a process, file write, or network connection.- They usually do not show the prompt, tool call, file context, or session flow behind that action.- That makes investigations harder and weakens policy decisions.-## How Asymptote Fits Together+## How Asymptote fits togetherAsymptote is built as a progression rather than a single all-or-nothing product.@@ -46,7 +46,7 @@ That gives teams a practical path:- centralize and govern that activity as usage expands- move into private deployment when compliance or infrastructure requirements demand it-## Choosing a Deployment Path+## Choosing a deployment pathUse these rules of thumb:diff --git a/docs/get-started/quickstart-developers.mdx b/docs/get-started/quickstart-developers.mdxindex 5299b5e4..7a537567 100644--- a/docs/get-started/quickstart-developers.mdx+++ b/docs/get-started/quickstart-developers.mdx@@ -41,7 +41,7 @@ beacon endpoint install<Note>The Linux tab uses the tarball on purpose. This page is a per-user setup, and the `.deb`/`.rpm`- packages install a **system-mode** endpoint managed by systemd — which writes to+ packages install a **system-mode** endpoint managed by systemd, which writes to`/var/log/beacon-agent/runtime.jsonl` instead, so every command below would report on the wronglog. If you want the system-mode package, follow [Linux](/platforms/linux) instead of this page.</Note>diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdxindex 4726d6f4..5f374c37 100644--- a/docs/get-started/quickstart.mdx+++ b/docs/get-started/quickstart.mdx@@ -5,7 +5,7 @@ description: "Choose the right Asymptote path for a local, managed, or private rStart here if you are deciding how to introduce Asymptote across a team. Asymptote can begin as open-source Agent Beacon telemetry across supported local, CI, and cloud surfaces, move into managed visibility and governance, or run in a private deployment for stricter infrastructure requirements.-## Choose a Deployment Path+## Choose a deployment path| Hosting Option | Use it when | Next step || -------------- | ----------- | --------- |@@ -15,7 +15,7 @@ Start here if you are deciding how to introduce Asymptote across a team. AsymptoSee [Hosting Options](/deployment/hosting-options) for the full comparison.-## Open Source Rollout Strategy+## Open source rollout strategyFor most Security and IT teams, the safest open-source path is staged. Local endpoint collection is usually the first evaluation path, then teams can add CI and cloud-agent surfaces where those agents run:@@ -27,7 +27,7 @@ For most Security and IT teams, the safest open-source path is staged. Local endThe open-source path is local-only by default. The endpoint agent does not require a Beacon-hosted account, remote policy fetch, or external network dependency during normal collection.-## Managed or Private Path+## Managed or private pathMove to Managed when a small pilot becomes an operating program: multiple teams, centralized search, governance, investigations, access control, and rollout support.@@ -35,7 +35,7 @@ Private Deployment is the path for regulated teams that need managed capabilitie[Contact us](https://asymptotelabs.ai/contact) to discuss Managed or Private Deployment.-## Pick Your Quickstart+## Pick your quickstart<Columns cols={2}><Card title="For Security & IT Teams" icon="building-shield" href="/get-started/quickstart-security-it">@@ -48,7 +48,7 @@ Private Deployment is the path for regulated teams that need managed capabilitie### Then pick your platform-Both paths install the endpoint agent locally, and that part differs by operating system — the+Both paths install the endpoint agent locally, and that part differs by operating system. Thepackage, the service manager, and how a fleet is deployed are not the same on each:<Columns cols={2}>@@ -63,10 +63,10 @@ package, the service manager, and how a fleet is deployed are not the same on ea</Card></Columns>-Capturing from CI jobs, cloud agents, or your own applications through the SDK needs none of this —-see [agent harness integrations](/runtimes).+Capturing from CI jobs, cloud agents, or your own applications through the SDK needs none of this.+See [agent harness integrations](/runtimes).-## Deeper Guides+## Deeper guides<Columns cols={2}><Card title="Asymptote Open Source" icon="download" href="/deployment/open-source">diff --git a/docs/guides/agent-runtime-telemetry.mdx b/docs/guides/agent-runtime-telemetry.mdxindex a51cf795..b11e0346 100644--- a/docs/guides/agent-runtime-telemetry.mdx+++ b/docs/guides/agent-runtime-telemetry.mdx@@ -45,7 +45,7 @@ event action: endpoint.validation```</Accordion>-## 1. Generate Or Find Activity+## 1. Generate or find activityRun a supported local agent harness, then check that Beacon has observed activity:@@ -55,7 +55,7 @@ beacon endpoint inventoryIf the validation event appears but runtime activity does not, check [Inventory Local Agent Runtimes](/guides/inventory) for installed, configured, managed, and observed state.-## 2. Open The Local Dashboard+## 2. Open the local dashboardOpen Log Search and Security Overview:@@ -63,7 +63,7 @@ Open Log Search and Security Overview:beacon endpoint dashboard --open```-## 3. Inspect Key Fields+## 3. Inspect key fields| Signal | Why it matters ||--------|----------------|@@ -78,7 +78,7 @@ beacon endpoint dashboard --openBeacon normalizes runtime-specific signals into the [Endpoint Event Schema](/telemetry-schema/event-schema), so analysts can search across runtimes with the same core fields.-## 4. Investigate Activity+## 4. Investigate activityIn Log Search, start with:@@ -89,7 +89,7 @@ In Log Search, start with:- MCP-like activity- Repository or working directory-## 5. Scan Locally+## 5. Scan locallyRun the active threat-detection rules over the runtime log:@@ -105,11 +105,11 @@ beacon scan --json --fail-on highManage the active rule store with [`beacon rules`](/cli/rules). Scanning is read-only and does not reach the network.-## 6. Forward For Detection+## 6. Forward for detectionBeacon writes normalized JSONL locally first. Forward it into Wazuh, Splunk HEC, Falcon LogScale, Elastic, Datadog, Sumo Logic, Rapid7 InsightIDR, Microsoft Sentinel, AWS S3, Google Cloud Storage, or a customer-managed shipper with [Log Forwarding](/log-forwarding).-## Key Features Demonstrated+## Key features demonstrated- Local collection health and last-event freshness.- Runtime coverage from installed/configured/observed inventory state.diff --git a/docs/guides/inventory.mdx b/docs/guides/inventory.mdxindex fdbcd594..dda04d1f 100644--- a/docs/guides/inventory.mdx+++ b/docs/guides/inventory.mdx@@ -11,7 +11,7 @@ Use it when you need to answer what is installed, what an agent may be able to aInventory explains what is present and observable on the host. [Detections](/detections) evaluate the observed event stream and emit findings when local rules match risky behavior.-## Inventory Areas+## Inventory areas<Columns cols={3}><Card title="Agent Harnesses" icon="list-check" href="/inventory/agent-harnesses">@@ -34,7 +34,7 @@ beacon endpoint installbeacon endpoint status```-## 1. Run A Basic Inventory+## 1. Run a basic inventoryStart with the default inventory view:@@ -56,7 +56,7 @@ Runtime log ~/.beacon/endpoint/logs/runtime.jsonl```</Accordion>-## 2. Include All Local Signals+## 2. Include all local signalsUse `--all` when you want local config files, skill manifests, MCP servers, hooks, OTLP settings, and observed runtime coverage in one report:@@ -70,7 +70,7 @@ Use `--system` for packaged or MDM-managed installs:sudo beacon endpoint inventory --system --all```-## 3. Export JSON For Review+## 3. Export JSON for reviewUse JSON output for support bundles, scripts, or fleet comparison:@@ -100,7 +100,7 @@ beacon endpoint inventory --json```</Accordion>-## Key Questions Answered+## Key questions answered- Which supported agent runtimes are installed or configured on this machine?- Which local agent skills are present under supported skill roots?@@ -109,7 +109,7 @@ beacon endpoint inventory --json- Which hooks, OTLP settings, or launch environment entries are present?- Which detected runtimes have recently produced Beacon events?-## What To Look For+## What to look for| Signal | Why it matters ||--------|----------------|@@ -123,13 +123,13 @@ beacon endpoint inventory --jsonInventory reads local endpoint state only. It does not authenticate to remote SaaS accounts, skill marketplaces, or MCP servers.-## View Results+## View results<Frame caption="Review runtime configurations, inventory status, and local telemetry coverage from the Inventory view."><img src="/images/agent_runtime_configurations.png" alt="Beacon dashboard Inventory view showing agent runtime configurations and coverage state." /></Frame>-### Runtime Coverage States+### Runtime coverage states- **Installed:** the runtime or executable appears to be present locally.- **Configured:** Beacon can see telemetry settings, hooks, launch environment entries, or other local config for the runtime.@@ -138,7 +138,7 @@ Inventory reads local endpoint state only. It does not authenticate to remote SaA runtime can be installed but not configured, configured but not observed, or observed only in a different user-mode or system-mode log.-### MCP Servers And Configs+### MCP servers and configsUse MCP inventory to spot tool exposure from local agent configs:@@ -147,7 +147,7 @@ Use MCP inventory to spot tool exposure from local agent configs:- Server references introduced by a specific runtime config- User-mode versus system-mode config differences-### Agent Skills+### Agent skillsUse skill inventory to spot durable local instruction surfaces:@@ -158,7 +158,7 @@ Use skill inventory to spot durable local instruction surfaces:Beacon reports skill names, paths, hashes, scope, and parser status. It does not retain `SKILL.md` instruction bodies in inventory output or inventory events.-## 4. Open Dashboard Inventory+## 4. Open dashboard inventoryOpen the dashboard for a quick visual check alongside top harnesses, models, repositories, MCP servers, and risk signals:@@ -166,7 +166,7 @@ Open the dashboard for a quick visual check alongside top harnesses, models, repbeacon endpoint dashboard --open```-## Key Features Demonstrated+## Key features demonstrated- Local runtime discovery without remote SaaS authentication.- Skill, MCP server, and config inventory from supported local paths.diff --git a/docs/guides/jamf-anthropic-openai-cursor-mdm.mdx b/docs/guides/jamf-anthropic-openai-cursor-mdm.mdxindex 2294f4ee..31ffdb8f 100644--- a/docs/guides/jamf-anthropic-openai-cursor-mdm.mdx+++ b/docs/guides/jamf-anthropic-openai-cursor-mdm.mdx@@ -31,7 +31,7 @@ flowchart LRVector --> S3[AWS S3]```-## Security Outcome+## Security outcomeAfter rollout:@@ -54,7 +54,7 @@ s3://<bucket>/<prefix>/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gzRuntime objects contain agent activity. Inventory objects contain agent configuration inventory such as known hooks, MCP servers, and skills where Beacon can inspect them locally.-## Product Coverage+## Product coverage| Product surface | Jamf step | What security receives || --- | --- | --- |@@ -83,7 +83,7 @@ BEACON_S3_PREFIX="beacon-prod" # goodBEACON_S3_PREFIX="beacon-prod/runtime" # avoid```-## AWS Permission+## AWS permissionScope write access to the Beacon prefix:@@ -108,7 +108,7 @@ Beacon does not store AWS credentials in endpoint configuration. The S3 helper wThat file is owned by root and mode `0600`.-## Jamf Policy Plan+## Jamf policy planCreate these policies in order:@@ -121,7 +121,7 @@ Create these policies in order:Keep policies 2, 3, and 4 separate during rollout. That makes failures easier to triage and avoids hiding user-context failures behind package installation success.-## Step 1: Install Beacon Package+## Step 1: install Beacon packageIn Jamf Pro:@@ -144,7 +144,7 @@ The package installs:/opt/beacon/jamf/scripts/install-cursor-hooks.sh```-## Step 2: Configure S3 And Claude Code+## Step 2: configure S3 and Claude CodeCreate a Jamf script named `Beacon - Configure S3 Forwarding`.@@ -225,7 +225,7 @@ This policy:- Installs Claude Code hooks for the console user.- Starts `com.beacon.endpoint.s3-forwarder`.-## Optional: Enable Endpoint Self-Updates+## Optional: enable endpoint self-updatesBeacon package self-updates are off by default. To let Beacon apply future signed package updates after the Jamf install, add a Jamf Files and Processes payload or post-install policy command:@@ -241,7 +241,7 @@ sudo /opt/beacon/bin/beacon endpoint update enable --check-onlyBoth commands require root. `auto` mode verifies release manifest checksums, Developer ID signature, and Gatekeeper install assessment before applying a signed package. `check-only` mode writes update status events to `/var/log/beacon-agent/system.jsonl` without downloading or applying packages.-## Step 3: Configure Cursor Hooks+## Step 3: configure Cursor hooksCreate a Jamf script named `Beacon - Configure Cursor Hooks`.@@ -304,7 +304,7 @@ The helper switches to the console user and runs:--log-path /var/log/beacon-agent/runtime.jsonl```-## Step 4: Configure Codex CLI+## Step 4: configure Codex CLICodex CLI runtime telemetry is OTLP-based. It reads OTLP settings from `~/.codex/config.toml`.@@ -324,11 +324,11 @@ endpoint = "http://127.0.0.1:4317"Preserve existing non-OTel Codex settings and ensure the final file is owned by the user. This step is required for Codex runtime telemetry. Optional Codex hooks can be installed separately when you want Codex sessions to trigger inventory heartbeats.-## Validate A Deployed Mac+## Validate a deployed MacRun these checks on a target Mac after each policy completes.-### 1. Confirm Services+### 1. Confirm services```bashsudo launchctl print system/com.beacon.endpoint.collector@@ -337,7 +337,7 @@ sudo launchctl print system/com.beacon.endpoint.s3-forwarderBoth services should be `running`.-### 2. Confirm Local Files+### 2. Confirm local files```bashls -l /var/log/beacon-agent/runtime.jsonl@@ -346,7 +346,7 @@ ls -l "/Library/Application Support/Beacon/Forwarders/s3-vector.toml"sudo test -r "/Library/Application Support/Beacon/Forwarders/s3-vector.env"```-### 3. Confirm S3 Forwarder Config+### 3. Confirm S3 forwarder config```bashsudo grep -E 'runtime.jsonl|inventory_state.jsonl|runtime/date|inventory/date|read_from' \@@ -364,7 +364,7 @@ key_prefix = "${BEACON_S3_PREFIX:-beacon}/runtime/date=%F/"key_prefix = "${BEACON_S3_PREFIX:-beacon}/inventory/date=%F/"```-### 4. Confirm Hook And Codex Config+### 4. Confirm hook and Codex configRun as the logged-in user:@@ -376,7 +376,7 @@ grep -n 'otel' ~/.codex/config.tomlClaude and Cursor should reference `beacon-hooks`. Codex should include `[otel]`, `[otel.exporter."otlp-grpc"]`, and `[otel.metrics_exporter."otlp-grpc"]`.-### 5. Generate Local Test Events+### 5. Generate local test eventsWrite a synthetic endpoint event:@@ -405,7 +405,7 @@ tail -n 5 /var/log/beacon-agent/runtime.jsonltail -n 5 /var/log/beacon-agent/inventory_state.jsonl```-### 6. Generate Product Events+### 6. Generate product eventsGenerate a Claude Code event:@@ -429,7 +429,7 @@ Generate a Cursor event by starting a new Cursor session after restart and sendisudo grep "beacon jamf cursor test" /var/log/beacon-agent/runtime.jsonl```-### 7. Confirm S3 Delivery+### 7. Confirm S3 deliveryVector batches uploads. Production configs use `timeout_secs = 300`, so allow up to five minutes.@@ -452,7 +452,7 @@ aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/date=<YYYY-MM-DD## Troubleshooting-### No S3 Objects+### No S3 objectsCheck the forwarder:@@ -515,13 +515,13 @@ Verify that the env file has non-secret settings without printing credentials:sudo sh -c 'sed -E "s/(AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN|BEACON_S3_BUCKET|AWS_REGION|BEACON_S3_PREFIX)=.*/\1=<redacted>/" "/Library/Application Support/Beacon/Forwarders/s3-vector.env"'```-### Cursor Hooks Are Missing+### Cursor hooks are missingConfirm the hook policy ran while a user was logged in. The helper exits when the console user is `root` or `loginwindow`.Run the hook policy again after login, then restart Cursor.-### Claude Code Events Are Missing+### Claude Code events are missingConfirm the S3 helper ran while a user was logged in, then check Claude settings as that user:@@ -531,7 +531,7 @@ grep -n 'BEACON_ENDPOINT_CLI\|beacon-hooks' ~/.claude/settings.jsonFully restart Claude Code after installing hooks.-### Codex Events Are Missing+### Codex events are missingConfirm Codex CLI is installed and the user config includes OTel:@@ -542,7 +542,7 @@ grep -n 'otel\|otlp-grpc\|127.0.0.1:4317' ~/.codex/config.tomlCodex runtime telemetry is OTLP-based. Re-run the Codex config policy for the logged-in user if the OTel block is missing.-### Inventory Is Empty+### Inventory is emptyForce inventory and inspect the local file:@@ -558,7 +558,7 @@ sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \tail -n 5 /var/log/beacon-agent/inventory_state.jsonl```-### Cloud Or Admin Products Are Missing+### Cloud or admin products are missingClaude Cowork, Claude Code cloud agents, Cursor Cloud Agents, CI agents, and SDK-instrumented OpenAI or Anthropic applications are not configured by this Mac MDM policy. Use their runtime-specific setup pages and validate those events at the collector or destination they target.diff --git a/docs/guides/jamf-falcon-mdm.mdx b/docs/guides/jamf-falcon-mdm.mdxindex 674f3c6a..ffef0cda 100644--- a/docs/guides/jamf-falcon-mdm.mdx+++ b/docs/guides/jamf-falcon-mdm.mdx@@ -41,7 +41,7 @@ Before creating the Jamf policy, prepare:For CrowdStrike data onboarding, parser setup, screenshots, and a direct HEC smoke test, see [CrowdStrike Falcon LogScale](/log-forwarding/falcon).-## Falcon HEC Settings+## Falcon HEC settingsCrowdStrike HEC values normally look like:@@ -62,7 +62,7 @@ Beacon stores the Falcon token only in the root-owned Vector environment file:That file is mode `0600` and is sourced by the Vector LaunchDaemon wrapper.-## Jamf Policy Setup+## Jamf policy setupJamf Pro separates package installation from script execution. Use the Packages payload to install the Beacon `.pkg`, then use a Scripts payload to run a wrapper that calls Beacon's packaged Jamf helper.@@ -73,7 +73,7 @@ For the most reliable rollout, use two policies:You can combine the package and script payloads in one policy if your Jamf workflow guarantees the package is installed before the script runs.-### 1. Upload The Beacon Package+### 1. Upload the Beacon packageUpload the signed Beacon endpoint package to Jamf Pro and add it to a policy using the Packages payload with the install action.@@ -91,7 +91,7 @@ The package installs:Current packages use `/opt/beacon/jamf/claude/falcon/repair-hooks-and-forwarder.sh`. Older internal smoke-test instructions may refer to a legacy helper path under `/opt/beacon/jamf/scripts`; use the path that exists in the package installed on the target Mac.-### 2. Add A Jamf Script Wrapper+### 2. Add a Jamf script wrapperAdd a script to Jamf Pro that invokes Beacon's packaged helper. The script must exist in Jamf Pro before it can be added to a policy.@@ -132,7 +132,7 @@ Use Jamf script parameter labels so policy editors know what each value means:Jamf script parameters are convenient for non-secret values such as endpoint, source, sourcetype, and repository. For the HEC token, prefer your Jamf secret injection mechanism when available. Avoid putting long-lived tokens directly in ordinary policy parameter fields or policy logs.-## What The Helper Does+## What the helper doesThe combined helper performs all endpoint and forwarding setup:@@ -153,7 +153,7 @@ The combined helper performs all endpoint and forwarding setup:End users do not need to run any Beacon command or edit any local config.-## Optional: Enable Endpoint Self-Updates+## Optional: enable endpoint self-updatesBeacon package self-updates are off by default. To let Beacon apply future signed package updates after the Jamf install, add a Jamf Files and Processes payload or post-install policy command:@@ -169,7 +169,7 @@ sudo /opt/beacon/bin/beacon endpoint update enable --check-onlyBoth commands require root. `auto` mode verifies release manifest checksums, Developer ID signature, and Gatekeeper install assessment before applying a signed package. `check-only` mode writes update status events to `/var/log/beacon-agent/system.jsonl` without downloading or applying packages.-## Manual Smoke Test+## Manual smoke testTo simulate the Jamf policy on one Mac, install the Beacon package, then run the packaged helper manually.@@ -196,11 +196,11 @@ sudo /opt/beacon/jamf/claude/falcon/repair-hooks-and-forwarder.sh \"json"```-## Validate A Deployed Mac+## Validate a deployed MacRun these commands on a target Mac after the Jamf policy completes.-### Check Services+### Check services```bashsudo launchctl print system/com.beacon.endpoint.collector@@ -209,7 +209,7 @@ sudo launchctl print system/com.beacon.endpoint.falcon-forwarderBoth services should report `state = running`.-### Check Forwarder Logs+### Check forwarder logs```bashsudo tail -n 50 /tmp/com.beacon.endpoint.falcon-forwarder.err@@ -221,14 +221,14 @@ Expected:no repeated auth, TLS, DNS, or HTTP errors in stderr```-### Check Local Files+### Check local files```bashls -l /var/log/beacon-agent/runtime.jsonlls -l /var/log/beacon-agent/inventory_state.jsonl```-### Check Vector Config+### Check Vector config```bashsudo grep -E 'runtime.jsonl|read_from|BEACON_FALCON_HEC_ENDPOINT|Authorization' \@@ -246,7 +246,7 @@ Authorization = "Bearer ${BEACON_FALCON_HEC_TOKEN}"Runtime forwarding starts at the end of the runtime log so historical session activity is not backfilled when Vector is first installed.-## Generate A Claude Hook Event+## Generate a Claude hook eventGenerate a unique Claude prompt in headless mode or in a normal Claude Code session:@@ -271,7 +271,7 @@ If you use a custom source, repository, or parser, adjust the query to match you## Troubleshooting-### Forwarder Is Not Running+### Forwarder is not runningCheck launchd and stderr:@@ -294,7 +294,7 @@ sudo /opt/beacon/jamf/claude/falcon/run-forwarder.shKeep that terminal open while generating a Claude hook event.-### Token Or Endpoint Is Wrong+### Token or endpoint is wrongCheck the env file without exposing secrets:@@ -304,7 +304,7 @@ sudo sh -c 'sed -E "s/(BEACON_FALCON_HEC_ENDPOINT|BEACON_FALCON_HEC_TOKEN|BEACONIf Vector reports `401`, `403`, or repository errors, regenerate the API key in Falcon and verify that the repository/index parameter matches the token scope.-### Claude Hooks Are Missing+### Claude hooks are missingFully restart Claude Code after the Jamf policy runs. Then inspect the user's Claude settings:@@ -314,7 +314,7 @@ grep -n 'BEACON_ENDPOINT_CLI\|beacon-hooks' ~/.claude/settings.jsonYou should see commands that call the packaged Beacon hook binary.-### Local Event Exists But Falcon Search Is Empty+### Local event exists but Falcon search is emptyConfirm the event appears in `/var/log/beacon-agent/runtime.jsonl`, then check Vector stderr for batching, TLS, DNS, or HTTP errors. Falcon searches can lag behind ingestion; wait a minute and search for the exact marker string.diff --git a/docs/guides/jamf-gcs-mdm.mdx b/docs/guides/jamf-gcs-mdm.mdxindex 45faebf6..353427de 100644--- a/docs/guides/jamf-gcs-mdm.mdx+++ b/docs/guides/jamf-gcs-mdm.mdx@@ -84,7 +84,7 @@ gcloud storage buckets add-iam-policy-binding "gs://${BEACON_GCS_BUCKET}" \Apply lifecycle, retention, logging, and CMEK controls in Google Cloud accordingto your organization's policy.-## 2. Deliver The Writer Credential+## 2. Deliver the writer credentialVector `0.56` supports a service-account JSON file through`GOOGLE_APPLICATION_CREDENTIALS` and GCE metadata credentials. Managed Macs do@@ -124,7 +124,7 @@ The packaged helper stores only the credential path in`/Library/Application Support/Beacon/Forwarders/gcs-vector.env`; the JSON staysin the externally managed location.-## 3. Configure The Jamf Policy+## 3. Configure the Jamf policyUpload the signed Beacon endpoint package, which includes:@@ -175,7 +175,7 @@ Runtime starts at `end` to avoid an unexpected historical upload. Inventorystarts at `beginning` so an initial snapshot created before Vector starts is notmissed.-## 4. Validate A Managed Mac+## 4. Validate a managed MacCheck services, files, and the non-secret configuration:@@ -238,7 +238,7 @@ gcloud iam service-accounts add-iam-policy-binding \--role roles/iam.serviceAccountTokenCreator```-## Credential Rotation+## Credential rotationCreate and deliver a new key before deleting the old one:diff --git a/docs/guides/jamf-s3-mdm.mdx b/docs/guides/jamf-s3-mdm.mdxindex e113d280..441ce1f9 100644--- a/docs/guides/jamf-s3-mdm.mdx+++ b/docs/guides/jamf-s3-mdm.mdx@@ -52,7 +52,7 @@ BEACON_S3_PREFIX="beacon-prod/runtime" # avoidThe helper normalizes old prefixes ending in `/runtime` or `/inventory`, but new deployments should use the root prefix.-## AWS Permission+## AWS permissionUse a bucket policy or IAM policy scoped to the Beacon prefix. Example:@@ -77,7 +77,7 @@ Beacon does not store AWS credentials in endpoint configuration. The Jamf helperThat file is mode `0600` and is sourced by the Vector LaunchDaemon wrapper.-## Jamf Policy Setup+## Jamf policy setupJamf Pro separates package installation from script execution. Use the Packages payload to install the Beacon `.pkg`, then use a Scripts payload to run a small wrapper that calls Beacon's packaged Jamf helper.@@ -88,7 +88,7 @@ For the most reliable rollout, use two policies:You can also combine package and script payloads in one policy if your Jamf workflow guarantees the package is installed before the script runs. The two-policy approach is easier to reason about and troubleshoot.-### 1. Upload The Beacon Package+### 1. Upload the Beacon packageUpload the signed Beacon endpoint package to Jamf Pro and add it to a policy using the Packages payload with the install action.@@ -104,7 +104,7 @@ The package installs:/opt/beacon/jamf/claude/s3/run-forwarder.sh```-### 2. Add A Jamf Script Wrapper+### 2. Add a Jamf script wrapperAdd a script to Jamf Pro that invokes Beacon's packaged helper. The script must exist in Jamf Pro before it can be added to a policy.@@ -150,7 +150,7 @@ Use Jamf script parameter labels so policy editors know what each value means:Jamf script parameters are convenient for non-secret values such as bucket, region, and prefix. For AWS credentials, prefer your Jamf secret injection mechanism, device identity, AWS profiles, web identity, or managed credential files. Avoid putting long-lived access keys directly in ordinary policy parameter fields or policy logs.-### 3. Inject AWS Provider Settings+### 3. Inject AWS provider settingsThe Beacon helper persists any AWS provider-chain variables it receives. Use one of these patterns:@@ -171,7 +171,7 @@ AWS_SECRET_ACCESS_KEY="..."/opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh```-### 4. Optionally Enable Endpoint Self-Updates+### 4. Optionally enable endpoint self-updatesBeacon package self-updates are off by default. To let Beacon apply future signed package updates after the Jamf install, add a Jamf Files and Processes payload or post-install policy command:@@ -187,7 +187,7 @@ sudo /opt/beacon/bin/beacon endpoint update enable --check-onlyBoth commands require root. `auto` mode downloads newer compatible signed packages from the release manifest after checksum, Developer ID signature, and Gatekeeper verification. `check-only` mode writes update status events to `/var/log/beacon-agent/system.jsonl` without downloading or applying packages.-## What The Helper Does+## What the helper doesThe combined helper performs all endpoint and forwarding setup:@@ -207,7 +207,7 @@ The combined helper performs all endpoint and forwarding setup:End users do not need to run any Beacon command or edit any local config.-## Expected S3 Layout+## Expected S3 layoutIf you configure:@@ -227,11 +227,11 @@ Runtime objects contain agent activity from `runtime.jsonl`.Inventory objects contain `inventory.heartbeat` and `inventory.snapshot` events from `inventory_state.jsonl`.-## Validate A Deployed Mac+## Validate a deployed MacRun these commands on a target Mac after the Jamf policy completes.-### Check Services+### Check services```bashsudo launchctl print system/com.beacon.endpoint.collector@@ -240,7 +240,7 @@ sudo launchctl print system/com.beacon.endpoint.s3-forwarderBoth services should be `running`.-### Check Local Files+### Check local files```bashls -l /var/log/beacon-agent/runtime.jsonl@@ -248,7 +248,7 @@ ls -l /var/log/beacon-agent/inventory_state.jsonlls -l /var/log/beacon-agent/inventory-state.json```-### Check Vector Config+### Check Vector config```bashsudo grep -E 'runtime.jsonl|inventory_state.jsonl|runtime/date|inventory/date|read_from' \@@ -270,9 +270,9 @@ Runtime forwarding starts at the end of the runtime log so historical session acInventory forwarding starts at the beginning of `inventory_state.jsonl` so the first inventory snapshot is not missed if the file was created before Vector began watching it.-## Generate Test Events+## Generate test events-### Runtime Event+### Runtime eventWrite a synthetic runtime validation event:@@ -282,7 +282,7 @@ sudo /opt/beacon/bin/beacon endpoint test-event \--log-path /var/log/beacon-agent/runtime.jsonl```-### Inventory Event+### Inventory eventWrite an inventory heartbeat and snapshot:@@ -303,7 +303,7 @@ tail -n 5 /var/log/beacon-agent/runtime.jsonltail -n 5 /var/log/beacon-agent/inventory_state.jsonl```-## Confirm S3 Delivery+## Confirm S3 deliveryVector batches uploads. Production configs use `timeout_secs = 300`, so allow up to five minutes unless you lower the batch timeout for a demo.@@ -324,7 +324,7 @@ aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/inventory/date=<YYYY-MM---region "$AWS_REGION" | gzip -dc | grep 'inventory.snapshot'```-## Live Demo Settings+## Live demo settingsFor a live demo, reduce the inventory TTL:@@ -371,7 +371,7 @@ sudo /opt/beacon/jamf/claude/s3/run-forwarder.shKeep that terminal open while generating runtime and inventory events.-## Test A Live Skill And MCP Change+## Test a live skill and MCP changeCreate a Claude Code skill:@@ -416,7 +416,7 @@ grep 'beacon-live-skill\|beacon_live_mcp' /var/log/beacon-agent/inventory_state.After Vector flushes, the same names should appear in an object under the S3 `inventory/` prefix.-## Restore Production Settings+## Restore production settingsAfter a demo, restore the production TTL:@@ -449,7 +449,7 @@ sudo env \## Troubleshooting-### No S3 Objects+### No S3 objectsCheck the forwarder:@@ -458,7 +458,7 @@ sudo launchctl print system/com.beacon.endpoint.s3-forwardersudo tail -n 100 /tmp/com.beacon.endpoint.s3-forwarder.err```-### Forwarder Is Not Loaded+### Forwarder is not loadedIf `launchctl` reports `Could not find service "com.beacon.endpoint.s3-forwarder"`,first confirm the managed files are still present:@@ -530,7 +530,7 @@ If launchd remains opaque after the repair, run Vector in the foreground:sudo /opt/beacon/jamf/claude/s3/run-forwarder.sh```-### Credentials Are Missing+### Credentials are missingCheck the env file without exposing secrets:@@ -538,7 +538,7 @@ Check the env file without exposing secrets:sudo sh -c 'sed -E "s/(AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN|BEACON_S3_BUCKET|AWS_REGION|BEACON_S3_PREFIX)=.*/\1=<redacted>/" "/Library/Application Support/Beacon/Forwarders/s3-vector.env"'```-### Inventory Is Empty+### Inventory is emptyForce inventory and inspect the local file:@@ -554,7 +554,7 @@ sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \tail -n 5 /var/log/beacon-agent/inventory_state.jsonl```-### Claude Hooks Are Missing+### Claude hooks are missingFully restart Claude Code after the Jamf policy runs. Then inspect the user's Claude settings:diff --git a/docs/guides/local-testing/dashboard.mdx b/docs/guides/local-testing/dashboard.mdxindex fcd42d7b..6e98e0c7 100644--- a/docs/guides/local-testing/dashboard.mdx+++ b/docs/guides/local-testing/dashboard.mdx@@ -18,7 +18,7 @@ beacon endpoint statusbeacon endpoint test-event```-## 1. Open The Dashboard+## 1. Open the dashboardStart the dashboard and open it in your browser:@@ -50,7 +50,7 @@ To inspect a specific runtime log:beacon endpoint dashboard --log-path /path/to/runtime.jsonl```-## 2. Test Log Search+## 2. Test log searchWrite a validation event, then open Log Search and confirm the event appears in the table.@@ -65,7 +65,7 @@ Use filters and quick filters to narrow the view by harness, model, severity, ca<img src="/images/dashboard-log-search.png" alt="Beacon endpoint Log Search view showing investigation filters, quick filters, event rows, and model-aware search controls." /></Frame>-## 3. Test Security Overview+## 3. Test security overviewOpen Security Overview after writing test events or generating local agent activity. Confirm the summary cards and inventory panels reflect the local runtime log you are testing.@@ -75,7 +75,7 @@ Open Security Overview after writing test events or generating local agent activSecurity Overview is useful for confirming event totals, needs-review counts, high or critical activity, denied or blocked activity, failed tools, sessions, top harnesses, top models, top repositories, MCP servers, and runtime inventory.-## Key Features Demonstrated+## Key features demonstrated- Dashboard startup against the expected runtime log.- Log Search visibility for a controlled validation event.diff --git a/docs/guides/local-testing/endpoint-validation.mdx b/docs/guides/local-testing/endpoint-validation.mdxindex 6240e686..f6718ee7 100644--- a/docs/guides/local-testing/endpoint-validation.mdx+++ b/docs/guides/local-testing/endpoint-validation.mdx@@ -18,7 +18,7 @@ beacon endpoint installbeacon endpoint status```-## Validation Workflow+## Validation workflow<Steps><Step title="Check health">@@ -32,7 +32,7 @@ beacon endpoint status</Step></Steps>-## Run The Validation Path+## Run the validation path```bash title="Validate local endpoint telemetry"beacon endpoint status@@ -57,7 +57,7 @@ wrote validation event: ok```</Accordion>-## View Results+## View resultsThe final status check should show a recent last Beacon event. If you open the dashboard, Log Search should include the synthetic validation event.@@ -65,7 +65,7 @@ The final status check should show a recent last Beacon event. If you open the dbeacon endpoint dashboard --open```-## Detailed Guides+## Detailed guides<Columns cols={2}><Card title="Run Endpoint Health Checks" icon="stethoscope" href="/guides/local-testing/health">diff --git a/docs/guides/local-testing/events.mdx b/docs/guides/local-testing/events.mdxindex c8ca6d8d..3e26085e 100644--- a/docs/guides/local-testing/events.mdx+++ b/docs/guides/local-testing/events.mdx@@ -17,7 +17,7 @@ Confirm endpoint telemetry is configured:beacon endpoint status```-## 1. Write A Test Event+## 1. Write a test eventRun `beacon endpoint test-event` with the default per-user endpoint paths:@@ -42,7 +42,7 @@ The command checks that the configured runtime log is writable, appends a synthebeacon endpoint validate-pipeline```-## 2. Print Validation Stages As JSON+## 2. Print validation stages as JSONUse JSON output when capturing evidence for support, scripts, or rollout checks:@@ -61,7 +61,7 @@ beacon endpoint test-event --json```</Accordion>-## 3. Validate A Specific Log Path+## 3. Validate a specific log pathIf you are testing a non-default runtime log, pass the path explicitly:@@ -75,7 +75,7 @@ For a system-mode deployment, use the system endpoint paths:sudo beacon endpoint test-event --system```-## 4. Test GitHub Copilot CLI Telemetry+## 4. Test GitHub Copilot CLI telemetryAfter `beacon endpoint install` has started the local collector, run a real Copilot CLI prompt with OTLP export enabled:@@ -95,7 +95,7 @@ beacon endpoint statusbeacon endpoint dashboard --open```-## Verify Results+## Verify resultsAfter writing the event, confirm it with status or the local dashboard:diff --git a/docs/guides/local-testing/health.mdx b/docs/guides/local-testing/health.mdxindex fae2bf1d..ea8d3190 100644--- a/docs/guides/local-testing/health.mdx+++ b/docs/guides/local-testing/health.mdx@@ -13,7 +13,7 @@ This guide covers status checks, doctor diagnostics, and harness discovery beforRun these checks after `beacon endpoint install` has configured the local endpoint agent.-## 1. Run Status+## 1. Run status`beacon endpoint status` gives the broadest local view. It reports the Agent Beacon CLI version, config path, runtime log path, collector health, service state, discovered harnesses, diagnostics, destinations, and last observed event.@@ -46,7 +46,7 @@ If you are validating a system-mode install from a managed package, check systemsudo beacon endpoint status --system```-## 2. Run Doctor+## 2. Run doctor`beacon endpoint doctor` runs pass/fail health checks and exits non-zero when a hard check fails. Add `--fix` when you want Beacon to apply supported safe remediations, such as creating a missing runtime log or repairing managed macOS collector service files.@@ -74,7 +74,7 @@ beacon endpoint doctor --fixFix mode reports any applied and skipped remediations. Skipped findings need operator review, such as invalid endpoint configuration, missing harness setup, missing observed events, unsafe log permissions, or service repair on non-macOS hosts.-## 3. Discover Harnesses+## 3. Discover harnessesUse discovery to compare configured and detected local runtimes before testing real agent activity.@@ -84,7 +84,7 @@ beacon endpoint discover --jsonConfirm that discovered harnesses match the local test scope. Hook-based runtimes such as Antigravity CLI, Claude Code, Cline, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, OpenCode, and Qwen Code may require user or project scoped hook installation before real activity appears.-## Key Signals+## Key signals- Collector is running and bound to local OTLP endpoints.- Runtime log path exists and is writable.diff --git a/docs/guides/local-testing/index.mdx b/docs/guides/local-testing/index.mdxindex 36a9ce6e..3256c7db 100644--- a/docs/guides/local-testing/index.mdx+++ b/docs/guides/local-testing/index.mdx@@ -28,7 +28,7 @@ Diagnostics: passing```</Accordion>-## Validation Workflow+## Validation workflow<Steps><Step title="Check endpoint health">@@ -48,7 +48,7 @@ Diagnostics: passing</Step></Steps>-## Guides In This Section+## Guides in this section<Columns cols={2}><Card title="Validate Endpoint Telemetry" icon="stethoscope" href="/guides/local-testing/endpoint-validation">@@ -64,13 +64,13 @@ Diagnostics: passingFor ephemeral agent telemetry in CI jobs, see [CI Telemetry](/cli/ci).-## Key Features Demonstrated+## Key features demonstrated- Verify local endpoint health before a rollout.- Write a synthetic endpoint event to prove the runtime log is writable.- Confirm the dashboard and MCP tools read the same local log.- Separate user-mode, system-mode, and custom log-path checks.-## When To Use Local Testing+## When to use local testingLocal testing is useful for developer evaluation, support triage, security review demos, and pilot preparation. For managed rollout guidance, see [Security & IT Rollout Guide](/security), [MDM Deployment](/mdm), and [Log Forwarding](/log-forwarding).diff --git a/docs/guides/local-testing/logs.mdx b/docs/guides/local-testing/logs.mdxindex a34fc857..e8529314 100644--- a/docs/guides/local-testing/logs.mdx+++ b/docs/guides/local-testing/logs.mdx@@ -17,7 +17,7 @@ Write a validation event first so the runtime log has a known record:beacon endpoint test-event```-## 1. Find The Active Runtime Log+## 1. Find the active runtime logUse status to print the configured runtime log path and last observed event:@@ -43,7 +43,7 @@ beacon endpoint status --jsonStatus also reports runtime-log source warnings when a system collector may be writing OTLP events to a different log than the one you are inspecting.-## 2. Compare User And System Paths+## 2. Compare user and system pathsDefault local evaluation uses per-user endpoint paths:@@ -61,7 +61,7 @@ sudo beacon endpoint test-event --systemKeep user-mode and system-mode checks separate. A dashboard opened against a user log will not show events written only to the system log, and a system-mode status check may report a different collector or launchd service state.-## 3. Understand Log Rotation+## 3. Understand log rotationBeacon keeps the active `runtime.jsonl` path stable and rotates it when the next write would exceed 10 MiB. By default, it keeps five numbered local archives next to the active file:@@ -76,7 +76,7 @@ runtime.jsonl.5External shippers should continue tailing the active `runtime.jsonl` path and use their normal file-rotation handling to checkpoint offsets. The local dashboard can inspect the active log and numbered archives when you need to review recent rotated events.-## 4. Test A Custom Log Path+## 4. Test a custom log pathUse `--log-path` when testing a temporary runtime log or a support reproduction:@@ -90,7 +90,7 @@ The same path should be used across the write, status, and dashboard checks.When a custom log rotates, archives use the same path plus a numeric suffix. For example, `/tmp/beacon/runtime.jsonl` rotates to `/tmp/beacon/runtime.jsonl.1`.-## Verify Results+## Verify results| Area | Expected result ||------|-----------------|diff --git a/docs/guides/local-testing/mcp.mdx b/docs/guides/local-testing/mcp.mdxindex 4b479453..24336e41 100644--- a/docs/guides/local-testing/mcp.mdx+++ b/docs/guides/local-testing/mcp.mdx@@ -9,7 +9,7 @@ Model Context Protocol (MCP) lets local assistants connect to tools and data souThis guide shows how to validate Beacon MCP locally, connect Cursor or Claude Code, and test that MCP query results match the same runtime log used by the dashboard.-## What Beacon MCP Exposes+## What Beacon MCP exposes`beacon mcp` exposes compact activity tools over MCP so an assistant can search, summarize, and fetch events from the local Beacon runtime log.@@ -31,7 +31,7 @@ beacon endpoint test-eventbeacon endpoint status```-## 1. Run MCP Doctor+## 1. Run MCP doctorValidate runtime log access, transport settings, readable event samples, and registered MCP tools:@@ -50,7 +50,7 @@ sample events: found```</Accordion>-## 2. Understand Transport Options+## 2. Understand transport optionsBeacon reads the same local `runtime.jsonl` used by the [dashboard](/cli/dashboard). MCP clients can launch Beacon over stdio, or local tools can connect to a running loopback HTTP JSON-RPC server.@@ -64,7 +64,7 @@ Use stdio for desktop MCP clients that launch Beacon as a subprocess. Use HTTP oDo not expose `beacon mcp serve --transport http` on a non-loopback interface. Beacon MCP is designed for local activity inspection, not remote administration.</Warning>-## Security Use Cases+## Security use casesMCP is useful when an analyst wants to ask a local assistant targeted questions about Beacon activity without opening the raw runtime log.@@ -73,7 +73,7 @@ MCP is useful when an analyst wants to ask a local assistant targeted questions- Pull one event by ID and compare it with the same event in the dashboard.- List available filters before narrowing an investigation to a specific command, file, session, or repository.-## 3. Test MCP End To End+## 3. Test MCP end to end<Steps><Step title="Write a known event">@@ -91,7 +91,7 @@ MCP is useful when an analyst wants to ask a local assistant targeted questions```</Step><Step title="Connect an MCP client">- Follow [Connect Cursor and Claude Code](#connect-cursor-and-claude-code) below, then ask the client to search recent Beacon activity or summarize activity from the last hour.+ Follow [Connect Cursor and Claude Code](#4-connect-cursor-and-claude-code) below, then ask the client to search recent Beacon activity or summarize activity from the last hour.</Step><Step title="Test loopback HTTP if needed">If your local tool uses HTTP JSON-RPC, validate the loopback transport before connecting.@@ -109,7 +109,7 @@ MCP is useful when an analyst wants to ask a local assistant targeted questions</Step></Steps>-## 4. Connect Cursor And Claude Code+## 4. Connect Cursor and Claude CodeBefore connecting a client, confirm Beacon is installed and resolve the absolute CLI path:@@ -193,7 +193,7 @@ Inside a Claude Code session, run `/mcp` and confirm Beacon is connected. Projec- Tools connect but return empty results: run `beacon endpoint status`; the runtime log may not have events yet.- Claude Code ignores project config: approve the `.mcp.json` server when prompted or check project-scope MCP settings.-## Key Features Demonstrated+## Key features demonstrated- Local MCP access to the same runtime log used by the dashboard.- Compact activity search, summary, event fetch, and filter discovery tools.diff --git a/docs/guides/macos-object-storage-system.mdx b/docs/guides/macos-object-storage-system.mdxindex 0c05a24d..49cffc93 100644--- a/docs/guides/macos-object-storage-system.mdx+++ b/docs/guides/macos-object-storage-system.mdx@@ -55,7 +55,7 @@ sudo /opt/beacon/bin/beacon endpoint status --systemsudo launchctl print system/com.beacon.endpoint.collector```-## 2. Configure Runtime Harnesses+## 2. Configure runtime harnessesObject storage forwarding begins after events reach Beacon's system logs.Configure the runtimes you use before troubleshooting the destination.@@ -90,7 +90,7 @@ ls -l \/var/log/beacon-agent/inventory_state.jsonl```-## 3. Choose A Destination+## 3. Choose a destinationUse a root prefix such as `beacon-prod`. Do not include `runtime` or`inventory`; Beacon appends those folders.@@ -290,7 +290,7 @@ external-account Workload Identity Federation on macOS. Configure lifecycle,retention, audit logging, and CMEK controls in Google Cloud rather than inBeacon.-### Forward To Both+### Forward to bothThe services have separate labels, configs, credentials, and checkpointdirectories. Install both helpers to forward the same local events to S3 and@@ -388,7 +388,7 @@ inspection commands with your administrator identity or a separate reader.Generate a real event from every configured harness and confirm its`harness.name` appears in a remote runtime object.-## 5. Operate And Troubleshoot+## 5. Operate and troubleshootThe forwarders persist checkpoints, so restarts and package upgrades resume fromthe last observed offsets. Runtime starts at the end on first install to avoiddiff --git a/docs/guides/use-cases.mdx b/docs/guides/use-cases.mdxindex 8dd5b06c..e0505db1 100644--- a/docs/guides/use-cases.mdx+++ b/docs/guides/use-cases.mdx@@ -7,7 +7,7 @@ description: "Common Beacon CLI workflows for inventorying and monitoring localUse these guides when you need practical steps for understanding local AI agent usage on an endpoint. They focus on inventorying what is present, confirming what Beacon can observe, and investigating runtime activity once events are flowing.-## Which Guide Should I Use?+## Which guide should I use?<Columns cols={2}><Card title="Inventory Local Agent Runtimes" icon="clipboard-list" href="/guides/inventory">@@ -18,7 +18,7 @@ Use these guides when you need practical steps for understanding local AI agent</Card></Columns>-## Fast Triage+## Fast triageUse these pages to answer:@@ -47,7 +47,7 @@ Last event: 2026-06-10T04:18:22Z```</Accordion>-## Key Features Demonstrated+## Key features demonstrated- Discover installed and configured local agent runtimes.- Inspect MCP servers, hooks, OTLP settings, and runtime config files.diff --git a/docs/inventory/agent-harnesses.mdx b/docs/inventory/agent-harnesses.mdxindex ef34bc11..0702a0de 100644--- a/docs/inventory/agent-harnesses.mdx+++ b/docs/inventory/agent-harnesses.mdx@@ -14,7 +14,7 @@ Use it to answer:- Which harnesses appear Beacon-managed versus customer-managed?- Which harnesses have recently emitted Beacon endpoint events?-## Coverage States+## Coverage states<Frame caption="Use Agent Harness Inventory to compare installed, configured, managed, and observed state across supported runtimes."><img src="/images/agent_harness_inventory.png" alt="Beacon dashboard Agent Harness Inventory view showing supported runtimes and coverage states." />@@ -31,7 +31,7 @@ Use it to answer:A harness can be installed but not configured, configured but not observed, or observed in a different user-mode or system-mode runtime log than the one you are reading.-## Review Workflow+## Review workflowStart with the fleet-friendly inventory view:@@ -57,7 +57,7 @@ For hook-based harnesses, inspect hook status directly:beacon endpoint hooks status --all```-## What To Look For+## What to look for- Expected harnesses that are installed but not configured.- Harnesses configured through customer-managed settings instead of Beacon-managed hooks or OTLP configuration.diff --git a/docs/inventory/mcp-servers.mdx b/docs/inventory/mcp-servers.mdxindex 45a18a4e..78b166c5 100644--- a/docs/inventory/mcp-servers.mdx+++ b/docs/inventory/mcp-servers.mdx@@ -16,7 +16,7 @@ Use it to review the tool surface an agent may be able to call from local configInventory reads local config and runtime state only. It does not authenticate to MCP servers, call their tools, or verify remote service permissions. For Claude Code, user-scoped MCP servers are commonly stored in `~/.claude.json`; project-scoped servers may also appear in project MCP/config files. For Cursor, Beacon inspects user and project `mcp.json` files.-## Run MCP Inventory+## Run MCP inventoryStart with the full inventory report when reviewing MCP server configuration alongside harness and skill state:@@ -36,7 +36,7 @@ Use system mode when the endpoint service and configuration are installed undersudo beacon endpoint inventory --system --all```-## Expected Versus Unexpected Servers+## Expected versus unexpected servers<Frame caption="Review MCP server inventory to see configured servers, source paths, scopes, and runtime context."><img src="/images/mcp_server_inventory.png" alt="Beacon dashboard MCP Server Inventory view showing configured MCP servers and their source context." />@@ -54,7 +54,7 @@ Common review questions:Beacon detections can evaluate emitted runtime telemetry when supported harnesses report MCP-like tool activity. Inventory explains that a server is configured or observable; detections evaluate the event stream when activity occurs.-## Beacon MCP Is Separate+## Beacon MCP is separateThe `beacon mcp` command group exposes local Beacon activity to MCP clients. That is different from inventorying third-party MCP servers referenced by agent configs.diff --git a/docs/inventory/skills.mdx b/docs/inventory/skills.mdxindex d7ecd7ef..0331fc68 100644--- a/docs/inventory/skills.mdx+++ b/docs/inventory/skills.mdx@@ -9,7 +9,7 @@ Skills are a local agent extension and configuration surface. A skill can add duBeacon inventory can help identify local skill manifests under supported skill roots. It follows symlinked skill directories, which is common for Claude Code skills linked from a shared `.agents/skills` store. It reports metadata such as names, paths, hashes, scope, modified time, and parser status. It does not retain `SKILL.md` instruction bodies in inventory output, dashboard responses, or inventory events.-## What Inventory Can Infer Today+## What inventory can infer today<Frame caption="Use Skills Inventory to review local skill manifests, scopes, hashes, and parser status."><img src="/images/skills_inventory.png" alt="Beacon dashboard Skills Inventory view showing local skill manifests and metadata." />@@ -35,7 +35,7 @@ Skill inventory is useful for:- Detecting manifest changes through hashes and modified-time metadata.- Identifying parser failures that may prevent Beacon from understanding a manifest consistently.-## What To Review Manually+## What to review manuallyInventory is intentionally conservative. It can identify local skill manifests and change indicators, but reviewers should inspect the skill contents, scripts, and repository context when deciding whether a skill is expected.@@ -49,7 +49,7 @@ Manual review should cover:Beacon does not claim to authenticate to or fully enumerate remote skill registries. Treat inventory as local endpoint visibility into supported paths, not as a registry audit.-## Runtime Telemetry And Detections+## Runtime telemetry and detectionsSkills may influence later runtime behavior. When a supported harness emits telemetry for tool calls, commands, file activity, approvals, or MCP-like tool usage, Beacon normalizes those events into the runtime log.diff --git a/docs/log-forwarding/ci-telemetry-exports.mdx b/docs/log-forwarding/ci-telemetry-exports.mdxindex 1d7cf26d..df72748a 100644--- a/docs/log-forwarding/ci-telemetry-exports.mdx+++ b/docs/log-forwarding/ci-telemetry-exports.mdx@@ -11,7 +11,7 @@ Beacon CI telemetry is written as normalized JSONL for a single ephemeral CI jobThis page covers export workflows for `beacon ci`. For persistent laptop or workstation forwarding, use [Log Forwarding](/log-forwarding).</Note>-## Export Contract+## Export contractBy default, `beacon ci exec` writes the CI runtime log to `$RUNNER_TEMP/beacon/runtime.jsonl` when `RUNNER_TEMP` is set. Otherwise it uses the system temp directory. Use `--log-path` when your workflow needs a stable artifact path.@@ -23,9 +23,9 @@ By default, `beacon ci exec` writes the CI runtime log to `$RUNNER_TEMP/beacon/rEach line in `runtime.jsonl` is one complete Beacon event using the [Endpoint Event Schema](/telemetry-schema/event-schema). Beacon applies redaction, sanitization, truncation, and event-size limits before events are written, so downstream artifacts receive the same normalized JSONL contract as local endpoint logs.-## Export Paths+## Export paths-### Workflow Artifact+### Workflow artifactThe **Agent Beacon CI Telemetry** GitHub Action uploads the CI runtime log as a workflow artifact by default:@@ -40,7 +40,7 @@ The **Agent Beacon CI Telemetry** GitHub Action uploads the CI runtime log as aUse the workflow artifact path when a security team or downstream job will retrieve the completed JSONL file after the run. Artifact access, retention, and download permissions stay under GitHub Actions controls.-### Object Storage Upload+### Object storage uploadFor CI runners that should hand off telemetry through object storage, `beacon ci exec` can upload the completed `runtime.jsonl` after telemetry validation.@@ -72,7 +72,7 @@ beacon ci exec --upload s3 --upload gcs -- claude --print "Review this repositorS3 upload uses `aws s3 cp` and the standard AWS credential provider chain. GCS upload uses `gcloud storage cp` when available, falling back to `gsutil cp`.-### GitHub Actions SIEM Forwarding+### GitHub Actions SIEM forwardingSet the Splunk or Falcon ingest token at the job or workflow level from a secret, then pass `forward` and `forward-endpoint` to the Agent Beacon action:@@ -103,7 +103,7 @@ See the sample workflows:For Falcon LogScale HEC, set `BEACON_CI_FALCON_HEC_TOKEN` and use `forward: falcon`.-### GitHub Actions Object Storage+### GitHub Actions object storageConfigure cloud credentials at the job level, then pass the upload destination to the Agent Beacon action:@@ -168,7 +168,7 @@ See the sample workflow:- [S3 and GCS upload telemetry workflow](https://github.com/Asymptote-Labs/agent-beacon/blob/main/examples/github-actions/s3-gcs-upload-telemetry.yml)-## Object Layout+## Object layoutIn GitHub Actions, object keys use this shape:@@ -184,7 +184,7 @@ Outside GitHub Actions, Beacon falls back to:Prefixes are optional. Beacon trims empty path parts and normalizes path separators before building the upload key.-## Destination Mapping+## Destination mappingThe JSONL artifact is the universal CI export contract. Existing destination packs and forwarding patterns can consume the same file after it is downloaded, copied, or routed into the customer-managed handoff path.@@ -202,7 +202,7 @@ The JSONL artifact is the universal CI export contract. Existing destination pac| Splunk | Use direct `--forward splunk`, or ingest the JSONL artifact with an existing Splunk pipeline || Falcon LogScale | Use direct `--forward falcon`, or ingest the JSONL artifact with an existing pipeline |-## Security Notes+## Security notesKeep cloud credentials in CI secret stores, OIDC roles, workload identity, or job-level credential actions. Do not pass cloud credentials through prompt text, action inputs, or committed workflow files.@@ -210,7 +210,7 @@ When object storage upload is configured, Beacon strips common AWS and Google crReview artifact access before rollout. CI runtime JSONL can contain prompt, tool, file, command, and run context where supported runtimes emit it. Beacon applies redaction, sanitization, truncation, and event-size limits before writing the artifact, but artifact retention, access, and downstream routing remain controlled by GitHub Actions, object storage, and your customer-managed pipeline.-## Failure Behavior+## Failure behaviorBy default, `beacon ci exec` fails the step when telemetry validation fails. Set `--require-telemetry=false` or the action input `require-telemetry: "false"` when telemetry health should warn but not gate the build.diff --git a/docs/log-forwarding/cloudwatch.mdx b/docs/log-forwarding/cloudwatch.mdxindex ac3820cf..5a187820 100644--- a/docs/log-forwarding/cloudwatch.mdx+++ b/docs/log-forwarding/cloudwatch.mdx@@ -3,7 +3,7 @@ title: "AWS CloudWatch Logs"description: "Forward Beacon endpoint events into AWS CloudWatch Logs with customer-managed Vector forwarding."----## Forwarding Overview+## Forwarding overviewBeacon `v0.0.42` added the [AWS CloudWatch Logs content pack](/concepts/core-concepts#aws-cloudwatch-logs-content-pack) for teams that want Beacon endpoint events forwarded into a customer-managed CloudWatch Logs log group for observability, security search, subscriptions, exports, or downstream detection workflows. Beacon remains the local JSONL producer and writes one source of truth, the active [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log). Your customer-managed [Vector forwarding](/concepts/core-concepts#vector-forwarding) agent tails that file and writes parsed Beacon events to CloudWatch Logs.@@ -154,7 +154,7 @@ vendor=beacon product=endpoint-agent destination.type=cloudwatch destination.modIf events do not appear, verify that Vector is reading the same runtime log path Beacon writes, that the AWS credential provider chain is available to the Vector process, that the log group name and region match your environment variables, and that IAM allows `logs:CreateLogStream`, `logs:DescribeLogStreams`, and `logs:PutLogEvents` for the selected log group.-## Content Handling+## Content handlingBeacon applies redaction, sanitization, truncation, and event-size limits before events are written to `runtime.jsonl` and forwarded to CloudWatch Logs. Review log group access, retention, subscription filters, and downstream consumers so retained telemetry matches your approved collection policy.diff --git a/docs/log-forwarding/customer-managed.mdx b/docs/log-forwarding/customer-managed.mdxindex 20122dcb..47559eee 100644--- a/docs/log-forwarding/customer-managed.mdx+++ b/docs/log-forwarding/customer-managed.mdx@@ -3,7 +3,7 @@ title: "Customer-Managed Log Pipelines"description: "Forward Beacon endpoint events from local JSONL through a customer-managed shipper, agent, or log pipeline."----## Pipeline Overview+## Pipeline overviewBeacon writes normalized [endpoint events](/concepts/core-concepts#endpoint-event) to the active local [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log). Customer-managed forwarding means your existing shipper, endpoint agent, Vector deployment, log pipeline, or SIEM collector tails that file and owns remote delivery.diff --git a/docs/log-forwarding/datadog.mdx b/docs/log-forwarding/datadog.mdxindex a39e3d79..c2420c17 100644--- a/docs/log-forwarding/datadog.mdx+++ b/docs/log-forwarding/datadog.mdx@@ -3,19 +3,19 @@ title: "Datadog"description: "Forward Beacon endpoint events into Datadog Logs with Datadog Agent custom log collection."----## Forwarding Overview+## Forwarding overviewBeacon streams endpoint events to Datadog by writing local JSONL and letting the Datadog Agent tail that file. Beacon does not store Datadog API keys or site configuration.Use this guide for a first-time macOS setup with Datadog Logs. You can complete the setup entirely from the command line; the Datadog UI steps below are optional and are included to show where the same values appear in the Datadog onboarding flow.-## What You Need+## What you need- Beacon CLI installed.- Datadog Agent installed and connected to your Datadog organization.- Permission to edit `/opt/datadog-agent/etc/datadog.yaml` and restart the Datadog Agent.-## Choose User Or System Mode+## Choose user or system mode| Setup | Beacon commands | Runtime log ||-------|-----------------|-------------|@@ -24,7 +24,7 @@ Use this guide for a first-time macOS setup with Datadog Logs. You can completeFor production or MDM deployment, prefer **system mode**. It avoids per-user home-directory permissions because the Datadog Agent can tail `/var/log/beacon-agent/runtime.jsonl`.-## 1. Install Beacon And Confirm Logs+## 1. Install Beacon and confirm logsFor local testing:@@ -49,7 +49,7 @@ sudo ls -l /var/log/beacon-agent/runtime.jsonl<img src="/images/datadog-runtime-log-file-check.png" alt="Terminal showing the Beacon runtime JSONL log exists at the user-mode path." /></Frame>-## 2. Enable Datadog Log Collection+## 2. Enable Datadog log collectionOpen the Datadog Agent config:@@ -69,7 +69,7 @@ You do not need to configure Datadog's OpenTelemetry Agent for this setup. Beaco<img src="/images/datadog-yaml.png" alt="Datadog Agent datadog.yaml showing logs_enabled set to true." /></Frame>-## 3. Optional: Review Custom File Logs In Datadog+## 3. Optional: review custom file logs in DatadogThis step is optional. Beacon generates the Datadog Agent config in the next step, so you do not need to copy anything manually from the Datadog UI.@@ -95,7 +95,7 @@ Leave multiline parsing blank. Beacon writes one JSON event per line.<img src="/images/datadog-configure-custom-log-source.png" alt="Datadog Custom Files setup page filled with Beacon runtime log path, service beacon-endpoint-agent, and source beacon." /></Frame>-## 4. Generate And Install The Beacon Config+## 4. Generate and install the Beacon configGenerate Beacon's Datadog content pack:@@ -122,7 +122,7 @@ sudo chmod 0644 /opt/datadog-agent/etc/conf.d/beacon.d/conf.yamlsudo launchctl kickstart -k system/com.datadoghq.agent```-## 5. Validate End To End+## 5. Validate end to endWrite a test event:@@ -158,7 +158,7 @@ Look for:<img src="/images/datadog-agent-status.png" alt="Datadog Agent status showing Logs Agent and beacon integration with Status OK, service beacon-endpoint-agent, source beacon, and logs sent." /></Frame>-## 6. Search In Datadog+## 6. Search in DatadogIn Datadog Log Explorer, search for:@@ -196,11 +196,11 @@ If Log Explorer is empty:- Run `beacon endpoint datadog validate` again.- Check `sudo datadog-agent status`.-## Content Handling+## Content handlingBeacon applies redaction, sanitization, truncation, and event-size limits before events are written to `runtime.jsonl` and tailed by Datadog Agent. Review log access, indexes, retention, and downstream consumers so retained telemetry matches your approved collection policy.-## OpenTelemetry Note+## OpenTelemetry noteDatadog's DDOT Collector is a good fit for OTel-first Linux or Kubernetes deployments, but Beacon's macOS endpoint v0 uses native Datadog Agent file log collection because it is the supported host path for tailing local JSONL files.diff --git a/docs/log-forwarding/elastic.mdx b/docs/log-forwarding/elastic.mdxindex cc368bb0..ff3c2fbc 100644--- a/docs/log-forwarding/elastic.mdx+++ b/docs/log-forwarding/elastic.mdx@@ -3,7 +3,7 @@ title: "Elastic"description: "Forward Beacon endpoint events into Elasticsearch and Kibana with Filebeat or standalone Elastic Agent."----## Forwarding Overview+## Forwarding overviewBeacon `v0.0.11` added an Elastic content pack for teams that want to search Beacon endpoint events in Elasticsearch and Kibana. Current Beacon releases write one local source of truth, the active [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log), and keep that handoff path bounded with local rotation. Filebeat or standalone Elastic Agent reads that file and owns the Elastic hosts, API keys, usernames, and passwords.@@ -76,7 +76,7 @@ beacon endpoint elastic down --pack-dir ./beacon-elastic-pack`beacon endpoint elastic up` and `beacon endpoint elastic down` are local validation helpers for macOS with Docker Desktop. For Linux endpoints or production deployments, use the generated Filebeat or standalone Elastic Agent configuration with your normal service manager.</Note>-## Elastic Cloud or self-managed Elastic+## Elastic cloud or self-managed ElasticGenerate the content pack on the endpoint or in your endpoint management workflow:diff --git a/docs/log-forwarding/falcon.mdx b/docs/log-forwarding/falcon.mdxindex 292136b8..de3102c8 100644--- a/docs/log-forwarding/falcon.mdx+++ b/docs/log-forwarding/falcon.mdx@@ -3,7 +3,7 @@ title: "CrowdStrike Falcon LogScale"description: "Forward Beacon endpoint telemetry to CrowdStrike Falcon LogScale with HTTP Event Collector."----## Forwarding Overview+## Forwarding overviewBeacon supports CrowdStrike Falcon HEC forwarding in two ways:@@ -31,7 +31,7 @@ In CrowdStrike Falcon, go to **Next-Gen SIEM** > **Log management** > **Data onb<img src="/images/crowdstrike_data_onboarding.png" alt="CrowdStrike Falcon navigation showing Next-Gen SIEM data onboarding under Log management." />-### Select the Falcon LogScale Collector+### Select the Falcon LogScale collectorSearch for `logscale`, select **Falcon LogScale Collector**, then choose **Configure**.@@ -301,7 +301,7 @@ sudo /opt/beacon/bin/beacon endpoint status --system --jsonsudo launchctl print system/com.beacon.endpoint.collector```-## Content Handling+## Content handlingBeacon applies redaction, sanitization, truncation, and event-size limits before events are written locally or forwarded through Falcon HEC. Review repository access, parser behavior, retention, and downstream consumers so retained telemetry matches your approved collection policy.diff --git a/docs/log-forwarding/index.mdx b/docs/log-forwarding/index.mdxindex 434ad122..8258da98 100644--- a/docs/log-forwarding/index.mdx+++ b/docs/log-forwarding/index.mdx@@ -3,7 +3,7 @@ title: "Log Forwarding"description: "Forward Beacon endpoint events from local JSONL into SIEMs, log aggregators, object storage, or local review workflows."----## Forwarding Overview+## Forwarding overviewBeacon writes normalized [endpoint events](/concepts/core-concepts#endpoint-event) as JSONL. The active [runtime log](/concepts/core-concepts#runtime-jsonl-log) is the handoff point for local review, [customer-managed log pipelines](/concepts/core-concepts#customer-managed-forwarding), log aggregators, object storage exporters, and most SIEM content packs. Beacon can also enable optional collector exporters for [Splunk HTTP Event Collector (HEC)](/concepts/core-concepts#splunk-hec) and [CrowdStrike Falcon LogScale HEC](/concepts/core-concepts#falcon-logscale-hec) during endpoint install or repair.@@ -29,7 +29,7 @@ Use system mode for MDM deployments so endpoint events land in the shared system## Destination categories-### Security Information and Event Management (SIEM)+### Security information and event management (SIEM)Use these paths when the destination is the security investigation or detection system.@@ -54,7 +54,7 @@ Use these paths when the destination is the security investigation or detection</Card></Columns>-### Log Aggregation+### Log aggregationUse these paths when Beacon JSONL feeds an observability store or customer-managed forwarding pipeline.@@ -73,7 +73,7 @@ Use these paths when Beacon JSONL feeds an observability store or customer-manag</Card></Columns>-### Object Storage+### Object storageUse these paths when Beacon JSONL should land in a customer-managed bucket for archive, lake, or downstream detection workflows.diff --git a/docs/log-forwarding/local-jsonl.mdx b/docs/log-forwarding/local-jsonl.mdxindex 4da36820..4bb42a74 100644--- a/docs/log-forwarding/local-jsonl.mdx+++ b/docs/log-forwarding/local-jsonl.mdx@@ -3,7 +3,7 @@ title: "Local JSONL"description: "Use Beacon's local runtime JSONL log as the default endpoint log and local dashboard source."----## Local Log Output+## Local log outputBeacon's default destination is the local [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log). The endpoint agent writes one normalized [endpoint event](/concepts/core-concepts#endpoint-event) per line and keeps the active path stable for local review, the Beacon dashboard, and downstream shippers.@@ -52,7 +52,7 @@ Open the local dashboard:beacon endpoint dashboard --open```-## Content Handling+## Content handlingBeacon applies redaction, sanitization, truncation, and event-size limits before events are written to local JSONL. Review filesystem access, archive retention, and any downstream readers so retained telemetry matches your approved collection policy.diff --git a/docs/log-forwarding/microsoft-sentinel.mdx b/docs/log-forwarding/microsoft-sentinel.mdxindex 6c4878d9..5c427aae 100644--- a/docs/log-forwarding/microsoft-sentinel.mdx+++ b/docs/log-forwarding/microsoft-sentinel.mdx@@ -3,7 +3,7 @@ title: "Microsoft Sentinel"description: "Forward Beacon endpoint events into Microsoft Sentinel with Azure Monitor Agent custom log collection."----## Forwarding Overview+## Forwarding overviewBeacon `v0.0.32` added the [Microsoft Sentinel content pack](/concepts/core-concepts#microsoft-sentinel-content-pack) for teams that want Beacon endpoint events in Log Analytics and Sentinel hunting workflows. Beacon remains the local JSONL producer and writes one source of truth, the active [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log). Azure Monitor Agent tails that file and sends new records through a Data Collection Rule (DCR) into a custom Log Analytics table.@@ -171,13 +171,13 @@ Use `queries.kql` for validation and starter hunting queries, including recent BUse `detections.kql` as example analytics rule logic. Review and tune thresholds, repository names, content handling policy, and severity mappings before enabling alerts in production.-## CEF, Syslog, and direct APIs+## CEF, syslog, and direct APIsMicrosoft Sentinel can also collect CEF and Syslog through Azure Monitor Agent, but the generated Beacon pack uses custom logs because Beacon events are rich structured JSON with prompts, tool calls, commands, files, runtime metadata, and optional raw fields. Flattening those events into CEF loses useful context.The Azure Monitor Logs Ingestion API can be useful for a centralized customer-managed forwarder, but it should not be configured directly in Beacon endpoint agent state. Direct API forwarding requires Microsoft Entra credentials, DCR identifiers, ingestion endpoints, batching, retries, and network failure handling. Keep those concerns outside Beacon's local endpoint collector unless you are building a separate managed forwarder.-## Content Handling+## Content handlingBeacon applies redaction, sanitization, truncation, and event-size limits before events are written to `runtime.jsonl` and forwarded to Microsoft Sentinel. Review workspace access, table retention, analytics rules, and downstream consumers so retained telemetry matches your approved collection policy.diff --git a/docs/log-forwarding/rapid7.mdx b/docs/log-forwarding/rapid7.mdxindex eeb706aa..b80b0cb2 100644--- a/docs/log-forwarding/rapid7.mdx+++ b/docs/log-forwarding/rapid7.mdx@@ -3,7 +3,7 @@ title: "Rapid7 InsightIDR"description: "Forward Beacon endpoint events into Rapid7 InsightIDR with a Custom Logs webhook event source."----## Forwarding Overview+## Forwarding overviewBeacon `v0.0.25` added Rapid7 InsightIDR support for teams that want Beacon endpoint events in Rapid7 Log Search and investigations. Current Beacon releases write one local source of truth, the active [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log), and keep that handoff path bounded with local rotation. Your customer-managed shipper or deployment tooling owns Rapid7 webhook URLs, checkpointing, rotation handling, and retries.@@ -148,7 +148,7 @@ vendor=beacon product=endpoint-agent destination.type=rapid7If events do not appear, verify that your forwarder is reading the same runtime log path Beacon writes, that the webhook URL is current, and that each Beacon JSONL line is preserved as a distinct event.-## Content Handling+## Content handlingBeacon applies redaction, sanitization, truncation, and event-size limits before events are written to `runtime.jsonl` and forwarded to Rapid7. Review event source access, retention, and downstream consumers so retained telemetry matches your approved collection policy.diff --git a/docs/log-forwarding/splunk.mdx b/docs/log-forwarding/splunk.mdxindex 15728266..83464110 100644--- a/docs/log-forwarding/splunk.mdx+++ b/docs/log-forwarding/splunk.mdx@@ -3,7 +3,7 @@ title: "Splunk HEC"description: "Send Beacon endpoint telemetry to Splunk HTTP Event Collector."----## Forwarding Overview+## Forwarding overviewBeacon writes normalized endpoint events as JSONL and can also send OTLP logs, traces, and metrics to Splunk HTTP Event Collector (HEC) through the bundled collector. The active runtime log remains the stable local handoff path and rotates locally. Use the built-in HEC destination when you want Beacon to forward directly, or configure a customer-managed forwarder to read the runtime log and send each JSON object to HEC.diff --git a/docs/log-forwarding/sumo.mdx b/docs/log-forwarding/sumo.mdxindex 4208daee..d1b0bc82 100644--- a/docs/log-forwarding/sumo.mdx+++ b/docs/log-forwarding/sumo.mdx@@ -3,7 +3,7 @@ title: "Sumo Logic"description: "Forward Beacon endpoint events into Sumo Logic with a Hosted Collector HTTP Logs & Metrics Source."----## Forwarding Overview+## Forwarding overviewBeacon `v0.0.20` added Sumo Logic support for teams that want Beacon endpoint events in Sumo Logic search, Live Tail, dashboards, and investigations. Current Beacon releases write one local source of truth, the active [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log), and keep that handoff path bounded with local rotation. Your customer-managed shipper or deployment tooling owns Sumo Source URLs, tokens, checkpointing, rotation handling, and retries.@@ -53,7 +53,7 @@ Copy the Source URL from the HTTP Logs & Metrics Source. You can use either:Keep the Source URL and token in your log shipper, endpoint-management secret store, or deployment tooling. Beacon does not store them.-## Install the Sumo pack+## Install the sumo packGenerate the Sumo Logic content pack for a managed system-mode deployment:@@ -175,7 +175,7 @@ _sourceCategory=security/agentbeacon "Beacon endpoint Sumo validation event"If events do not appear, verify that your forwarder is reading the same runtime log path Beacon writes, that the Source URL or Auth Header token is current, that `X-Sumo-Category` and `X-Sumo-Fields` match your searches, and that message boundary detection treats each JSONL line as a distinct event.-## Content Handling+## Content handlingBeacon applies redaction, sanitization, truncation, and event-size limits before events are written to `runtime.jsonl` and forwarded to Sumo Logic. Review source access, retention, and downstream consumers so retained telemetry matches your approved collection policy.diff --git a/docs/log-forwarding/wazuh.mdx b/docs/log-forwarding/wazuh.mdxindex 99a11933..24195f3b 100644--- a/docs/log-forwarding/wazuh.mdx+++ b/docs/log-forwarding/wazuh.mdx@@ -3,7 +3,7 @@ title: "Wazuh"description: "Forward Beacon endpoint events into Wazuh with localfile ingestion."----## Forwarding Overview+## Forwarding overviewBeacon writes normalized AI runtime telemetry as one JSON object per line in the active local [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log). Beacon keeps that handoff path bounded with local rotation. Wazuh ingests those events with a standard `localfile` input and Beacon's generated Wazuh rules.@@ -221,7 +221,7 @@ Expected rule IDs:- `100500`: base Beacon endpoint runtime event.- `100550`: AI agent workflow telemetry, such as prompts, tool activity, and file activity.-## Wazuh Dashboard+## Wazuh dashboardOpen Wazuh Dashboard, then go to **Threat Hunting** → **Events**. Start with one of these filters:diff --git a/docs/manage/configure-s3-data-connector.mdx b/docs/manage/configure-s3-data-connector.mdxindex c3745061..7340579d 100644--- a/docs/manage/configure-s3-data-connector.mdx+++ b/docs/manage/configure-s3-data-connector.mdx@@ -11,7 +11,7 @@ Do not make the bucket public. Do not grant write or delete permissions.At the end of setup, send Asymptote the full IAM role ARN for the role you create.-## Customer Steps+## Customer steps1. Send Asymptote the S3 location details.@@ -106,7 +106,7 @@ At the end of setup, send Asymptote the full IAM role ARN for the role you creat- KMS key ARN, if applicable- A small sample event file or example JSONL row-## Event File Requirements+## Event file requirementsUse newline-delimited JSON, with one complete JSON object per line. Each event should include a UTC-compatible timestamp and stable fields for user, host, repository, branch, agent runtime, event action, and event category when available.diff --git a/docs/manage/connect-okta.mdx b/docs/manage/connect-okta.mdxindex 30f12d9d..7eb6811f 100644--- a/docs/manage/connect-okta.mdx+++ b/docs/manage/connect-okta.mdx@@ -22,7 +22,7 @@ Connect Okta from the Asymptote dashboard to automatically populate the users, gAfter the connector is authorized, Asymptote automatically syncs Okta data into the users, groups, and devices tabs in the dashboard.-## Generate an Okta API Token+## Generate an Okta API tokenCreate the Okta API token from the Okta Admin Console:diff --git a/docs/manage/connect-slack.mdx b/docs/manage/connect-slack.mdxindex 66199917..f0ac2e5d 100644--- a/docs/manage/connect-slack.mdx+++ b/docs/manage/connect-slack.mdx@@ -23,7 +23,7 @@ Connect Slack from the Asymptote dashboard to send alert notifications to a SlacAfter Slack redirects back to Asymptote, choose the channel where alert notifications should be delivered.-## Choose a Notification Channel+## Choose a notification channel1. Open the Slack connector in Asymptote.2. Search for the channel by name or channel ID.@@ -35,7 +35,7 @@ After Slack redirects back to Asymptote, choose the channel where alert notifica<img src="/images/slack_connector.png" alt="Asymptote Slack connector setup screen with channel selection and test notification controls." /></Frame>-## Add Private Channels+## Add private channelsSlack only allows apps to post in private channels after the app has been added to that channel.diff --git a/docs/mdm/index.mdx b/docs/mdm/index.mdxindex 294e3524..6a943d8a 100644--- a/docs/mdm/index.mdx+++ b/docs/mdm/index.mdx@@ -3,7 +3,7 @@ title: "MDM Deployment"description: "Plan managed macOS deployment of Beacon with Jamf Pro, Rippling, Fleet, or another MDM."----## Deployment Overview+## Deployment overviewBeacon's macOS package is designed for security and IT rollout through MDM. A signed and notarized `.pkg` installs Beacon under `/opt/beacon`, creates system endpoint configuration, loads the local collector LaunchDaemon, and writes endpoint events to `/var/log/beacon-agent/runtime.jsonl`. Optional Splunk HEC or Falcon LogScale HEC settings add collector destinations while preserving the local runtime log.diff --git a/docs/mdm/jamf/claude.mdx b/docs/mdm/jamf/claude.mdxindex 3a5350e1..ee1dc7ae 100644--- a/docs/mdm/jamf/claude.mdx+++ b/docs/mdm/jamf/claude.mdx@@ -17,7 +17,7 @@ Use this page as the Claude-specific Jamf entry point. For complete managed forw</Card></Columns>-## What The Jamf Claude Flow Installs+## What the Jamf Claude flow installsThe packaged Claude Jamf helpers configure:@@ -29,7 +29,7 @@ The packaged Claude Jamf helpers configure:End users should not need to run Beacon commands or edit local Beacon configuration when the Jamf policy is configured correctly.-## Packaged Helper Scripts+## Packaged helper scriptsThe macOS package includes these Claude-specific helpers:diff --git a/docs/platforms/linux-deployment-profile.mdx b/docs/platforms/linux-deployment-profile.mdxindex 8a3c4b1d..c2ce3368 100644--- a/docs/platforms/linux-deployment-profile.mdx+++ b/docs/platforms/linux-deployment-profile.mdx@@ -3,8 +3,7 @@ title: "Linux Deployment Profile"description: "What the Beacon endpoint agent depends on, what it costs to run, and how to verify both yourself"----A reference for reviewing Beacon before deploying it. Each claim comes with the command that checks-it, so you can confirm any of this yourself.+A reference for reviewing Beacon before deploying it. Each claim comes with the command that checks it, so you can confirm any of this yourself.## Kernel surface@@ -26,7 +25,7 @@ Everything it uses from the kernel:| TCP loopback | Three listeners on `127.0.0.1` | Collector cannot start || `flock(2)` | Serializing writes to the runtime log | Degrades on some network filesystems; fine on local disk || `fork`/`exec` | One short-lived hook process per agent event | Hook capture stops; OpenTelemetry capture continues |-| Ordinary file I/O | Config and log | — |+| Ordinary file I/O | Config and log | None || `/proc/1/comm` | systemd detection | Falls back to a supervised collector, which does not restart on exit or start at boot |To see the syscalls for yourself:@@ -38,13 +37,12 @@ sudo strace -f -c -o /tmp/install.trace beacon endpoint install --system --dry-r## Binaries-Three static executables, no shared libraries, no minimum glibc version. They run the same on a-minimal or older userland as on a full one.+Three static executables, no shared libraries, no minimum glibc version. They run the same on a minimal or older userland as on a full one.| Binary | Role | Resident? ||---|---|---|-| `beacon-otelcol` | Collector | Yes — the only long-running process |-| `beacon-hooks` | Records one agent event | No — forks and exits |+| `beacon-otelcol` | Collector | Yes, the only long-running process |+| `beacon-hooks` | Records one agent event | No, it forks and exits || `beacon` | CLI | No |```bash@@ -61,17 +59,15 @@ Measured on Ubuntu 24.04 / amd64 after a live Claude Code session.| | Measured | Notes ||---|---|---|-| Resident memory | 28–58 MiB | Hard ceiling 128 MiB (`memory_limiter`) |-| CPU, idle | 0.03–0.3% of one core | Two timers: 1s memory check, 5s batch flush |+| Resident memory | 28-58 MiB | Hard ceiling 128 MiB (`memory_limiter`) |+| CPU, idle | 0.03-0.3% of one core | Two timers: 1s memory check, 5s batch flush || Threads | 15 | Go runtime, scales with available cores || Disk | ≤60 MB | 10 MiB × 5 rotations, oldest discarded || Per agent event | one `fork`/`exec`, one `flock`, one append | Process exits immediately |### Caveats-- Both figures are ranges, not averages. They come from a supervised collector and a- systemd-managed one, which is most of the spread — memory in particular depends on how much the- Go runtime has been asked to do before it settles.+- Both figures are ranges, not averages. They come from a supervised collector and a systemd-managed one, which accounts for most of the spread. Memory in particular depends on how much the Go runtime has been asked to do before it settles.- These numbers come from a virtualized sandbox, where syscalls are slower than on bare metal.Expect equal or better on your own hardware.@@ -115,9 +111,7 @@ ss -ltnp | grep beacon-otelcol## Pinning it to housekeeping cores-If you isolate cores for latency-sensitive work, keep Beacon off them. It only has two slow timers,-but a timer firing on an `isolcpus` or `nohz_full` core is exactly what isolating that core was-meant to prevent.+If you isolate cores for latency-sensitive work, keep Beacon off them. It only has two slow timers, but a timer firing on an `isolcpus` or `nohz_full` core is exactly what isolating that core was meant to prevent.```ini# /etc/systemd/system/beacon-collector.service.d/10-resources.conf@@ -134,8 +128,7 @@ sudo systemctl daemon-reload && sudo systemctl restart beacon-collectorsystemctl show beacon-collector -p CPUAffinity -p CPUQuota -p MemoryMax```-Put this in a drop-in rather than editing the unit file directly. `beacon endpoint doctor --fix`-rewrites the unit, which would wipe out your changes; drop-ins are left alone.+Put this in a drop-in rather than editing the unit file directly. `beacon endpoint doctor --fix` rewrites the unit, which would wipe out your changes; drop-ins are left alone.## Uninstall@@ -144,8 +137,7 @@ sudo apt remove beacon # keeps config and collected logssudo apt purge beacon # removes them```-On RPM systems, `dnf remove` keeps `/etc/beacon/endpoint` and `/var/log/beacon-agent`. Remove them-with `sudo beacon endpoint uninstall --system` if you want the data gone.+On RPM systems, `dnf remove` keeps `/etc/beacon/endpoint` and `/var/log/beacon-agent`. Remove them with `sudo beacon endpoint uninstall --system` if you want the data gone.## Relateddiff --git a/docs/platforms/linux.mdx b/docs/platforms/linux.mdxindex 363eae71..71093b84 100644--- a/docs/platforms/linux.mdx+++ b/docs/platforms/linux.mdx@@ -3,17 +3,13 @@ title: "Linux Install"description: "Install the Beacon endpoint on Linux with a .deb or .rpm, and understand how the systemd service is managed"----Beacon runs a local collector on your machine, points your agent runtimes at it, and writes-normalized events to a JSONL log you own. On Linux the collector runs as a systemd service.+Beacon runs a local collector on your machine, points your agent runtimes at it, and writes normalized events to a JSONL log you own. On Linux the collector runs as a systemd service.-Installing the package is the whole setup. It unpacks the binaries, performs the system-mode-install, registers and starts the systemd unit, and configures the runtime of the user who ran the-install. There is no second command to run.+Installing the package is the whole setup. It unpacks the binaries, performs the system-mode install, registers and starts the systemd unit, and configures the runtime of the user who ran the install. There is no second command to run.## Install-Download the package for your architecture from the-[latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest) and install it:+Download the package for your architecture from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest) and install it:<CodeGroup>```bash title="Debian, Ubuntu"@@ -25,13 +21,11 @@ sudo dnf install ./beacon_<version>_linux_amd64.rpm```</CodeGroup>-`amd64` and `arm64` packages are published for both formats. The package puts `beacon` on your-`PATH`, so every command below works by name.+`amd64` and `arm64` packages are published for both formats. The package puts `beacon` on your `PATH`, so every command below works by name.### Without root, or without a package manager-If you are not an administrator on the machine, or you would rather not touch system paths, use the-tarball and install in user mode:+If you are not an administrator on the machine, or you would rather not touch system paths, use the tarball and install in user mode:```bash title="Tarball install, no root required"LATEST_URL="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"@@ -60,14 +54,9 @@ beacon versionbeacon endpoint install```-The version comes from the current release rather than a number you have to keep up to date, and-the architecture comes from `uname -m`: `x86_64` maps to the published `amd64` archive and-`aarch64` to `arm64`. An architecture Beacon does not publish stops the run before anything is-downloaded.+The version comes from the current release rather than a number you have to keep up to date, and the architecture comes from `uname -m`: `x86_64` maps to the published `amd64` archive and `aarch64` to `arm64`. An architecture Beacon does not publish stops the run before anything is downloaded.-The archive contains three binaries — the `beacon` CLI, the `beacon-hooks` adapter that captures-tool activity, and the `beacon-otelcol` collector. All three are needed, and all three are-statically linked with no shared-library dependencies.+The archive contains three binaries: the `beacon` CLI, the `beacon-hooks` adapter that captures tool activity, and the `beacon-otelcol` collector. All three are needed, and all three are statically linked with no shared-library dependencies.See [User-mode install](#user-mode-install) for what this sets up and its one caveat.@@ -93,10 +82,9 @@ Harness: Claude Code telemetry=enabledLast event: present```-`beacon endpoint doctor --system` goes further, checking the whole chain — unit, collector, config,-log permissions, and each harness's settings — and printing the command to fix anything it finds.+`beacon endpoint doctor --system` goes further. It checks the whole chain (unit, collector, config, log permissions, and each harness's settings) and prints the command to fix anything it finds.-On a fresh install it reports one warning, and it is not a problem:+On a fresh install it reports one warning, which is not a problem:```Beacon endpoint doctor: warn@@ -105,8 +93,7 @@ harness_observed: warn target=claude_code (telemetry is configured but no matchiSummary: 0 failure(s), 1 warning(s)```-That says "configured correctly, but you have not used it yet." It clears the first time you run-your agent. What matters is `0 failure(s)`.+That means "configured correctly, but not used yet". It clears the first time you run your agent. What matters is `0 failure(s)`.<Warning>One failure is worth knowing by name, because a system endpoint can be perfectly healthy and@@ -118,10 +105,7 @@ your agent. What matters is `0 failure(s)`.action="sudo beacon endpoint user-config repair-installed --system"```- A system-mode endpoint runs as root, so it has to work out *whose* agent settings to configure.- If it could not identify you at install time, the collector still starts and reports healthy —- it simply has nothing sending to it. Run the action above as the user whose sessions should be- captured and it clears.+ A system-mode endpoint runs as root, so it has to work out whose agent settings to configure. If it could not identify you at install time, the collector still starts and reports healthy, but nothing is sending to it. Run the action above as the user whose sessions should be captured and it clears.</Warning>If you would rather confirm the pipeline before running a real session, write a synthetic event:@@ -131,8 +115,7 @@ sudo beacon endpoint test-event --system```<Note>- Pass `--system` here. Without it the command targets the *user-mode* log under `~/.beacon`, which- is not the log a system install writes to — so it would report success against the wrong file.+ Pass `--system` here. Without it the command targets the user-mode log under `~/.beacon`, which is not the log a system install writes to, so it would report success against the wrong file.</Note>## Using it@@ -143,14 +126,12 @@ Nothing to remember. Run your agent the way you normally do:claude```-Prompts, the commands the agent runs, files it reads and writes, token counts and cost, approvals-and denials all land in `/var/log/beacon-agent/runtime.jsonl` — one JSON object per line. Two-independent paths feed it, which is why a gap in one still leaves you with data:+Prompts, the commands the agent runs, files it reads and writes, token counts and cost, and approvals and denials all land in `/var/log/beacon-agent/runtime.jsonl`, one JSON object per line. Two independent paths feed it, so a gap in one still leaves you with data:| Path | Carries ||---|---|-| OpenTelemetry | Prompts, tool calls, token usage, cost — via `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317` in your agent settings |-| Hooks | Session start and end, tool use, permission requests, subagent activity, reasoning |+| OpenTelemetry | Prompts, tool calls, token usage, and cost, through `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317` in your agent settings |+| Hooks | Session start and end, tool use, permission requests, subagent activity, and reasoning |Both are loopback-only. Nothing leaves the machine.@@ -174,19 +155,13 @@ See the [event schema](/telemetry-schema/event-schema) for the full field refere| Runtime log | `/var/log/beacon-agent/runtime.jsonl` || Agent runtime | Claude Code and Codex CLI settings for the installing user, pointed at `127.0.0.1:4317` |-That last row is worth knowing about. A system-mode endpoint runs as root, so the install has to-work out *whose* agent settings to configure — the collector is useless if nothing is exporting to-it. Beacon uses `SUDO_USER`, which is set for every normal install path, and falls back to asking-logind who has an active session. If it cannot identify anyone, it says so instead of failing, and-you can configure yourself later:+That last row is worth knowing about. A system-mode endpoint runs as root, so the install has to work out whose agent settings to configure, and the collector is useless if nothing exports to it. Beacon uses `SUDO_USER`, which is set for every normal install path, and falls back to asking logind who has an active session. If it cannot identify anyone, it says so instead of failing, and you can configure yourself later:```bash title="Configure your own agent runtime against an already-installed endpoint"sudo beacon endpoint user-config repair-installed --system```-Other users on the same machine run the same command for themselves. They all export to the same-collector and the same log, which is why `/var/log/beacon-agent/runtime.jsonl` is group- and-world-writable — hooks run as the logged-in user and append to it directly.+Other users on the same machine run the same command for themselves. They all export to the same collector and the same log. That is why `/var/log/beacon-agent/runtime.jsonl` is group- and world-writable: hooks run as the logged-in user and append to it directly.## Managing the service@@ -198,8 +173,7 @@ systemctl restart beacon-collectorjournalctl -u beacon-collector -f```-`Restart=always` means systemd brings the collector back if it exits, and `WantedBy=multi-user.target`-means it starts on boot. Both are set by the install; you do not need to configure them.+`Restart=always` means systemd brings the collector back if it exits, and `WantedBy=multi-user.target` means it starts on boot. Both are set by the install; you do not need to configure them.If the unit is missing or broken, repair it without reinstalling the package:@@ -209,9 +183,7 @@ sudo beacon endpoint doctor --system --fix## Choosing a service backend-Beacon decides which service manager to use by reading what is actually running as PID 1. It does-not check whether `systemctl` exists on `PATH` — inside a container that is often true while systemd-is not running at all, and trusting it would produce a unit nothing ever starts.+Beacon decides which service manager to use by reading what is actually running as PID 1. It does not check whether `systemctl` exists on `PATH`. Inside a container that is often true while systemd is not running at all, and trusting it would produce a unit nothing ever starts.You can override the choice:@@ -226,47 +198,35 @@ sudo beacon endpoint install --system --service none| `systemd` | Require systemd; fail rather than fall back || `none` | A supervised background collector, tracked by a pidfile |-Use `--service systemd` in automation where a silent fallback would be worse than a failure. Use-`--service none` in a container or on a distribution without systemd.+Use `--service systemd` in automation where a silent fallback would be worse than a failure. Use `--service none` in a container or on a distribution without systemd.## User-mode install-If you do not want a system service — a shared host where you are not root, or a machine where you-only want your own sessions captured — install in user mode:+Install in user mode if you do not want a system service, either because you are not root on a shared host or because you only want your own sessions captured:```bash title="User-mode install"beacon endpoint install```-This writes everything under `~/.beacon/endpoint` and registers a `systemctl --user` unit. One-caveat has no macOS equivalent and is worth stating plainly: **a `--user` unit stops when you log-out**, unless linger is enabled for your account. Beacon enables it during install when it can:+This writes everything under `~/.beacon/endpoint` and registers a `systemctl --user` unit. One caveat has no macOS equivalent and is worth stating plainly: **a `--user` unit stops when you log out**, unless linger is enabled for your account. Beacon enables it during install when it can:```bash title="Keep a user-mode collector running after logout"sudo loginctl enable-linger $USER```-When it could not, `beacon endpoint install` and `beacon endpoint repair` say so at the end of the-run and print that exact command, and `beacon endpoint doctor` keeps reporting it until it is-fixed. Beacon checks the resulting linger state rather than the exit status of its own attempt, so-this reflects whether the collector really will survive logout. Without linger, a user-mode-collector works while you are logged in and stops collecting after you log out.+When it could not, `beacon endpoint install` and `beacon endpoint repair` say so at the end of the run and print that exact command, and `beacon endpoint doctor` keeps reporting it until it is fixed. Beacon checks the resulting linger state rather than the exit status of its own attempt, so this reflects whether the collector really will survive logout. Without linger, a user-mode collector works while you are logged in and stops collecting after you log out.## Without systemd-The supervised backend covers hosts with no init system to talk to — containers, minimal images,-distributions using OpenRC or SysV:+The supervised backend covers hosts with no init system to talk to, such as containers, minimal images, and distributions using OpenRC or SysV:```bash title="Supervised collector"beacon endpoint install --service none```-The collector runs as a background process tracked by a pidfile. It collects normally, but nothing-restarts it if it exits and nothing starts it at boot. `beacon endpoint status` states this rather-than reporting the same health as a managed service, so you are never misled about what you have.+The collector runs as a background process tracked by a pidfile. It collects normally, but nothing restarts it if it exits and nothing starts it at boot. `beacon endpoint status` states this rather than reporting the same health as a managed service, so you are never misled about what you have.-For CI, prefer `beacon ci exec`, which wraps a single command in an ephemeral collector and needs no-service at all.+For CI, prefer `beacon ci exec`, which wraps a single command in an ephemeral collector and needs no service at all.## Updates@@ -277,12 +237,7 @@ sudo beacon endpoint update --checksudo beacon endpoint update --apply```-`--apply` downloads the release package for your platform, verifies its SHA-256, installs it with-`dpkg` or `rpm`, restarts the collector, and rolls back if the new version fails its health check.-Verification is checksum-over-HTTPS from GitHub Releases — the same trust root you used to download-the package in the first place. macOS additionally verifies Apple notarization; Linux has no-OS-level equivalent, and `beacon endpoint update` reports which verification it performed rather-than implying both.+`--apply` downloads the release package for your platform, verifies its SHA-256, installs it with `dpkg` or `rpm`, restarts the collector, and rolls back if the new version fails its health check. Verification is checksum-over-HTTPS from GitHub Releases, the same trust root you used to download the package in the first place. macOS additionally verifies Apple notarization; Linux has no OS-level equivalent, and `beacon endpoint update` reports which verification it performed rather than implying both.Upgrading the package keeps your configuration and your collected log.@@ -292,9 +247,7 @@ Upgrading the package keeps your configuration and your collected log.sudo apt remove beacon # or: sudo dnf remove beacon```-Removal stops and deletes the service and takes the binaries away, but leaves-`/etc/beacon/endpoint` and `/var/log/beacon-agent` alone — collected telemetry is not something a-package removal should destroy. To remove those too:+Removal stops and deletes the service and takes the binaries away, but leaves `/etc/beacon/endpoint` and `/var/log/beacon-agent` alone. Collected telemetry is not something a package removal should destroy. To remove those too:```bash title="Remove everything"sudo apt purge beacon@@ -312,7 +265,7 @@ sudo beacon endpoint uninstall --system<Columns cols={2}><Card title="Deployment profile" icon="shield-check" href="/platforms/linux-deployment-profile">- What it depends on, what it costs to run, and how to verify both — for a security review.+ What it depends on, what it costs to run, and how to verify both, for a security review.</Card><Card title="Endpoint status" icon="circle-info" href="/cli/endpoint-status">Inspect collector health, runtime log state, harnesses, and diagnostics.diff --git a/docs/platforms/macos.mdx b/docs/platforms/macos.mdxindex 0be8e825..e345c14f 100644--- a/docs/platforms/macos.mdx+++ b/docs/platforms/macos.mdx@@ -3,11 +3,9 @@ title: "macOS"description: "Install the Beacon endpoint on macOS with Homebrew or the signed package, and understand how the launchd service is managed"----Beacon runs a local collector on your machine, points your agent runtimes at it, and writes-normalized events to a JSONL log you own. On macOS the collector runs as a launchd job.+Beacon runs a local collector on your machine, points your agent runtimes at it, and writes normalized events to a JSONL log you own. On macOS the collector runs as a launchd job.-There are two ways in, and which one you want depends on whether you are setting up your own machine-or a fleet.+There are two ways in, and which one you want depends on whether you are setting up your own machine or a fleet.## Your own machine@@ -17,9 +15,7 @@ brew install beaconbeacon endpoint install```-`beacon endpoint install` with no flags is a **user-mode** install: everything lives under-`~/.beacon/endpoint`, the launchd job is a LaunchAgent in your own domain, and nothing needs root.-That is the right choice for a single developer.+`beacon endpoint install` with no flags is a **user-mode** install: everything lives under `~/.beacon/endpoint`, the launchd job is a LaunchAgent in your own domain, and nothing needs root. That is the right choice for a single developer.Then confirm it:@@ -28,19 +24,13 @@ beacon endpoint statusbeacon endpoint doctor```-On a fresh install `doctor` reports one warning — `harness_observed`, saying telemetry is configured-but no matching event has been seen yet. That is not a problem; it clears the first time you run your-agent. What matters is `0 failure(s)`.+On a fresh install `doctor` reports one warning, `harness_observed`, which says telemetry is configured but no matching event has been seen yet. That is not a problem. It clears the first time you run your agent. What matters is `0 failure(s)`.## A managed fleet-For deployment across machines, use the signed, notarized, and stapled `.pkg` attached to each-release. Installing it performs a **system-mode** install: configuration under-`/Library/Application Support/Beacon/Endpoint`, a LaunchDaemon, and the runtime log at-`/var/log/beacon-agent/runtime.jsonl`.+For deployment across machines, use the signed, notarized, and stapled `.pkg` attached to each release. Installing it performs a **system-mode** install: configuration under `/Library/Application Support/Beacon/Endpoint`, a LaunchDaemon, and the runtime log at `/var/log/beacon-agent/runtime.jsonl`.-The package also configures the console user's agent runtime, because a system endpoint runs as root-and the collector is useless if nothing is exporting to it.+The package also configures the console user's agent runtime, because a system endpoint runs as root and the collector is useless if nothing is exporting to it.<Columns cols={2}><Card title="Jamf Pro" icon="screwdriver-wrench" href="/mdm/jamf">@@ -69,8 +59,7 @@ launchctl print "gui/$(id -u)/com.beacon.endpoint.collector.user"sudo launchctl print system/com.beacon.endpoint.collector```-`KeepAlive` restarts the collector if it exits and `RunAtLoad` starts it at login or boot. Both are-set by the install; you do not configure them.+`KeepAlive` restarts the collector if it exits and `RunAtLoad` starts it at login or boot. Both are set by the install; you do not configure them.If the job or its plist is missing or broken, repair it without reinstalling:@@ -80,12 +69,11 @@ beacon endpoint doctor --fix## What is macOS-specific-Most of Beacon behaves identically everywhere — the event schema, the collector, hooks, the-dashboard, threat detection. These are the parts that do not:+Most of Beacon behaves identically everywhere: the event schema, the collector, hooks, the dashboard, and threat detection. These are the parts that do not:| Area | On macOS ||---|---|-| Service manager | launchd — a LaunchAgent in user mode, a LaunchDaemon in system mode |+| Service manager | launchd. A LaunchAgent in user mode, a LaunchDaemon in system mode || System config | `/Library/Application Support/Beacon/Endpoint` || Service definition | `~/Library/LaunchAgents/com.beacon.endpoint.collector.user.plist`, or `/Library/LaunchDaemons/com.beacon.endpoint.collector.plist` || Package | Signed, notarized, and stapled `.pkg`, Apple Silicon |@@ -93,9 +81,7 @@ dashboard, threat detection. These are the parts that do not:| Fleet management | Jamf, Fleet, and Rippling assets ship in the package || Log forwarding helpers | Bundled Vector helpers for Falcon, S3, and GCS |-Two of those have no Linux equivalent and are worth knowing if you run a mixed fleet: notarization-gives macOS an OS-level authenticity check that Linux has no counterpart for, and the MDM assets are-macOS-only. See [Linux](/platforms/linux) for how that platform differs.+Two of those have no Linux equivalent and are worth knowing if you run a mixed fleet: notarization gives macOS an OS-level authenticity check that Linux has no counterpart for, and the MDM assets are macOS-only. See [Linux](/platforms/linux) for how that platform differs.## Updates@@ -106,10 +92,7 @@ sudo beacon endpoint update --checksudo beacon endpoint update --apply```-`--apply` downloads the release package, verifies its SHA-256 **and** its Apple notarization,-installs it, restarts the collector, and rolls back if the new version fails its health check. The-command reports which verification it performed, so a mixed fleet can tell the two platforms apart:-macOS gets `sha256+notarization`, Linux gets `sha256` because there is no OS-level equivalent.+`--apply` downloads the release package, verifies its SHA-256 **and** its Apple notarization, installs it, restarts the collector, and rolls back if the new version fails its health check. The command reports which verification it performed, so a mixed fleet can tell the two platforms apart: macOS gets `sha256+notarization`, Linux gets `sha256` because there is no OS-level equivalent.`--apply` requires a package install. A Homebrew install is upgraded with `brew upgrade beacon`.diff --git a/docs/platforms/windows.mdx b/docs/platforms/windows.mdxindex 7b9adf13..7b8506c2 100644--- a/docs/platforms/windows.mdx+++ b/docs/platforms/windows.mdx@@ -3,18 +3,13 @@ title: "Windows Install"description: "Install the Beacon endpoint on Windows with the MSI, and understand how the Windows service is managed"----Beacon runs a local collector on your machine, points your agent runtimes at it, and writes-normalized events to a JSONL log you own. On Windows the collector runs as a Windows service,-managed by the Service Control Manager.+Beacon runs a local collector on your machine, points your agent runtimes at it, and writes normalized events to a JSONL log you own. On Windows the collector runs as a Windows service, managed by the Service Control Manager.-Installing the package is the whole setup. It unpacks the binaries, performs the system-mode-install, registers and starts the `BeaconCollector` service, and configures the runtime of the-interactive user. There is no second command to run.+Installing the package is the whole setup. It unpacks the binaries, performs the system-mode install, registers and starts the `BeaconCollector` service, and configures the runtime of the interactive user. There is no second command to run.## Install-Download `BeaconEndpointAgent-<version>-x64.msi` from the-[latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest) and install it:+Download `BeaconEndpointAgent-<version>-x64.msi` from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest) and install it:<CodeGroup>```powershell title="Interactive"@@ -26,26 +21,20 @@ msiexec /i BeaconEndpointAgent-<version>-x64.msi /qn /l*v install.log```</CodeGroup>-The install needs administrator rights, because it writes under `%ProgramData%` and registers a-service. Elevation is requested for you when you double-click the package; a silent install must-already be running elevated, which is the normal case for Intune, SCCM, or a management agent.+The install needs administrator rights, because it writes under `%ProgramData%` and registers a service. Elevation is requested for you when you double-click the package. A silent install must already be running elevated, which is the normal case for Intune, SCCM, or a management agent.<Warning>- **The installer is not code-signed yet.** Windows SmartScreen will warn that the publisher is- unknown, and you will need to choose "More info" then "Run anyway". Verify what you downloaded- against the published `.sha256` before you do:+ **The installer is not code-signed yet.** Windows SmartScreen warns that the publisher is unknown, and you need to choose "More info" then "Run anyway". Verify what you downloaded against the published `.sha256` first:```powershell(Get-FileHash BeaconEndpointAgent-<version>-x64.msi -Algorithm SHA256).Hash```- Authenticode signing is planned; until then the checksum is the integrity check the package has.+ Authenticode signing is planned. Until then, the checksum is the only integrity check the package has.</Warning><Note>- x64 only. There is no Windows ARM package, because there is no Windows ARM build of the collector- the package would need to contain — an installer that put the CLI on disk without it would report- no collector found on a machine where you had just installed Beacon.+ x64 only. There is no Windows ARM package, because there is no Windows ARM build of the collector to put in it. An installer that shipped the CLI without a collector would report "no collector found" on a machine where you had just installed Beacon.</Note>## Confirm it worked@@ -64,9 +53,7 @@ Harness: Claude Code telemetry=enabledLast event: present```-`running=true` alone does not tell you which backend you got. Beacon falls back to a supervised-background collector when it cannot register a service, and the fallback reports `running=true` too.-The JSON output names it:+`running=true` alone does not tell you which backend you got. Beacon falls back to a supervised background collector when it cannot register a service, and the fallback also reports `running=true`. The JSON output names the backend:```powershell title="Confirm you have a real service, not the fallback"beacon endpoint status --system --json | Select-String '"kind"'@@ -76,14 +63,11 @@ beacon endpoint status --system --json | Select-String '"kind"'"service":{"label":"BeaconCollector","loaded":true,"running":true,"kind":"windows-service"}```-`"kind":"windows-service"` is what you want. `"kind":"none"` means the supervised fallback — see-[user-mode install](#user-mode-install) for what that costs you.+`"kind":"windows-service"` is what you want. `"kind":"none"` means the supervised fallback. See [user-mode install](#user-mode-install) for what that costs you.-`beacon endpoint doctor --system` goes further, checking the whole chain — service, collector,-config, log permissions, and each harness's settings — and printing the command to fix anything it-finds.+`beacon endpoint doctor --system` goes further. It checks the whole chain (service, collector, config, log permissions, and each harness's settings) and prints the command to fix anything it finds.-On a fresh install it reports one warning, and it is not a problem:+On a fresh install it reports one warning, which is not a problem:```Beacon endpoint doctor: warn@@ -92,37 +76,32 @@ harness_observed: warn target=claude_code (telemetry is configured but no matchiSummary: 0 failure(s), 1 warning(s)```-That says "configured correctly, but you have not used it yet." It clears the first time you run-your agent. What matters is `0 failure(s)`.+That means "configured correctly, but not used yet". It clears the first time you run your agent. What matters is `0 failure(s)`.-To confirm the pipeline before running a real session, write a synthetic event from an elevated-prompt:+To confirm the pipeline before running a real session, write a synthetic event from an elevated prompt:```powershell title="Prove the collector is receiving and writing events"beacon endpoint test-event --system```<Note>- Pass `--system` here. Without it the command targets the *user-mode* log under your profile, which- is not the log a system install writes to — so it would report success against the wrong file.+ Pass `--system` here. Without it the command targets the user-mode log under your profile, which is not the log a system install writes to, so it would report success against the wrong file.</Note>## Using it-Nothing to remember. Run your agent the way you normally do:+Run your agent the way you normally do:```powershellclaude```-Prompts, the commands the agent runs, files it reads and writes, token counts and cost, approvals-and denials all land in `C:\ProgramData\Beacon\Endpoint\logs\runtime.jsonl` — one JSON object per-line. Two independent paths feed it, which is why a gap in one still leaves you with data:+Prompts, the commands the agent runs, files it reads and writes, token counts and cost, and approvals and denials all land in `C:\ProgramData\Beacon\Endpoint\logs\runtime.jsonl`, one JSON object per line. Two independent paths feed it, so a gap in one still leaves you with data:| Path | Carries ||---|---|-| OpenTelemetry | Prompts, tool calls, token usage, cost — via `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317` in your agent settings |-| Hooks | Session start and end, tool use, permission requests, subagent activity, reasoning |+| OpenTelemetry | Prompts, tool calls, token usage, and cost, through `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317` in your agent settings |+| Hooks | Session start and end, tool use, permission requests, subagent activity, and reasoning |Both are loopback-only. Nothing leaves the machine.@@ -140,7 +119,7 @@ See the [event schema](/telemetry-schema/event-schema) for the full field refere| Step | Result ||---|---|-| Unpack | `beacon.exe`, `beacon-hooks.exe` and `beacon-otelcol.exe` under `%ProgramFiles%\Beacon\bin` |+| Unpack | `beacon.exe`, `beacon-hooks.exe`, and `beacon-otelcol.exe` under `%ProgramFiles%\Beacon\bin` || System install | Config and collector config under `%ProgramData%\Beacon\Endpoint` || Service | `BeaconCollector`, registered with the SCM, automatic start, restart on failure || Runtime log | `%ProgramData%\Beacon\Endpoint\logs\runtime.jsonl` |@@ -149,25 +128,15 @@ See the [event schema](/telemetry-schema/event-schema) for the full field refereTwo of those rows deserve explanation.-**The log permission grant.** A system-mode collector runs as `LocalSystem` and creates the log;-hooks run as *you* and append to it. `%ProgramData%` subdirectories inherit an ACL where only-administrators and SYSTEM may write, so without an explicit grant every hook write fails with access-denied — and nothing reports it, because `status` and `doctor` describe the collector rather than the-hooks exporting to it. The install grants `INTERACTIVE` write access on the log directory, and-`doctor` checks the grant is still there.+**The log permission grant.** A system-mode collector runs as `LocalSystem` and creates the log, while hooks run as you and append to it. `%ProgramData%` subdirectories inherit an ACL where only administrators and SYSTEM may write, so without an explicit grant every hook write fails with access denied. Nothing reports it either, because `status` and `doctor` describe the collector rather than the hooks exporting to it. The install grants `INTERACTIVE` write access on the log directory, and `doctor` checks the grant is still there.-**The agent runtime row.** A system-mode endpoint is installed by an administrator or by a management-agent running as `LocalSystem`, neither of which is necessarily the person at the keyboard — and the-collector is useless if nothing is exporting to it. Beacon works out who is signed in at the console-and configures their runtime. If it cannot identify anyone, it says so instead of failing, and you can-configure yourself later:+**The agent runtime row.** A system-mode endpoint is installed by an administrator or by a management agent running as `LocalSystem`, neither of which is necessarily the person at the keyboard, and the collector is useless if nothing exports to it. Beacon works out who is signed in at the console and configures their runtime. If it cannot identify anyone, it says so instead of failing, and you can configure yourself later:```powershell title="Configure your own agent runtime against an already-installed endpoint"beacon endpoint user-config repair-installed --system```-Other users on the same machine run the same command for themselves. They all export to the same-collector and the same log.+Other users on the same machine run the same command for themselves. They all export to the same collector and the same log.## Managing the service@@ -179,14 +148,9 @@ Restart-Service BeaconCollectorGet-Service BeaconCollector```-The install sets automatic start with a delayed start, so the collector comes back after a reboot-without anyone signing in, and does not compete with the rest of boot. It also sets recovery actions:-three restarts at 5, 15 and 60 seconds, with the failure count resetting after a day of health. Three-escalating restarts rather than unlimited immediate ones — a collector that cannot start at all should-leave a visible stopped service rather than thrash.+The install sets automatic start with a delayed start, so the collector comes back after a reboot without anyone signing in and does not compete with the rest of boot. It also sets recovery actions: three restarts at 5, 15, and 60 seconds, with the failure count resetting after a day of health. Three escalating restarts rather than unlimited immediate ones means a collector that cannot start at all leaves a visible stopped service rather than thrashing.-The SCM captures no stdout, so there is no journal equivalent. The collector's own log is the place to-look, and `doctor` reads it for you.+The SCM captures no stdout, so there is no journal equivalent. The collector's own log is the place to look, and `doctor` reads it for you.If the service is missing or broken, repair it without reinstalling the package:@@ -196,8 +160,7 @@ beacon endpoint doctor --system --fix## User-mode install-If you do not want a system service — a machine where you are not an administrator, or where you only-want your own sessions captured — install in user mode:+Install in user mode if you do not want a system service, either because you are not an administrator on the machine or because you only want your own sessions captured:```powershell title="User-mode install"beacon endpoint install@@ -205,27 +168,18 @@ beacon endpoint installThis writes everything under `%USERPROFILE%\.beacon\endpoint`.-One limitation has no macOS or Linux equivalent and is worth stating plainly: **Windows has no-per-user service manager.** There is no counterpart to `systemctl --user` or launchd's per-user-domain, so a user-mode install runs a supervised background collector tracked by a pidfile. Two-consequences, both of which `beacon endpoint status` states in-band rather than leaving you to-discover:+One limitation has no macOS or Linux equivalent: **Windows has no per-user service manager.** There is no counterpart to `systemctl --user` or launchd's per-user domain, so a user-mode install runs a supervised background collector tracked by a pidfile. That has two consequences, both of which `beacon endpoint status` reports:- **Nothing restarts it.** If the collector exits, it stays down until you start it again.- **It does not survive sign-out.** Windows ends the session's processes at logoff.-On Linux the equivalent gap is fixable with `loginctl enable-linger`. Windows has no equivalent, which-is why the system-mode install is the recommended path here even for a single-user machine.+On Linux the equivalent gap is fixable with `loginctl enable-linger`. Windows has no counterpart, which is why system-mode install is the recommended path here even on a single-user machine.## Which shell your agent uses-Worth knowing if you are debugging a hook that is not firing: Claude Code on Windows executes hook-commands through **Git Bash**, not `cmd.exe` or PowerShell. Beacon's installed hook commands are-written for that, and Git Bash ships with Git for Windows, which Claude Code already requires.+This matters when you are debugging a hook that is not firing. Claude Code on Windows runs hook commands through **Git Bash**, not `cmd.exe` or PowerShell. Beacon's installed hook commands are written for that, and Git Bash ships with Git for Windows, which Claude Code already requires.-This was measured rather than assumed — a probe installed several candidate command forms and-reported which ones ran. If you write your own hook commands alongside Beacon's, they are parsed by-bash too.+If you write your own hook commands alongside Beacon's, bash parses those too.## Updates@@ -235,16 +189,10 @@ Download the newer MSI and install it over the top:msiexec /i BeaconEndpointAgent-<newer>-x64.msi /qn```-The upgrade stops the endpoint, replaces the binaries, and brings it back. That ordering is required-rather than tidy: Windows cannot replace a file that a running process holds open, so an upgrade that-left the collector running would either fail, defer the replacement to your next reboot, or silently-keep the old binary. Your configuration and collected log survive the upgrade.+The upgrade stops the endpoint, replaces the binaries, and brings it back. That ordering is required: Windows cannot replace a file a running process holds open, so an upgrade that left the collector running would fail, defer the replacement to your next reboot, or silently keep the old binary. Your configuration and collected log survive the upgrade.<Note>- `beacon endpoint update --apply` does not work on Windows yet. It reports that automatic apply is- only supported for a package install it recognises, rather than pretending to update. Self-update- is waiting on code signing — downloading and running an unsigned installer automatically would be a- worse trade than doing it by hand.+ `beacon endpoint update --apply` does not work on Windows yet. It reports that automatic apply is only supported for a package install it recognizes, rather than pretending to update. Self-update is waiting on code signing, because downloading and running an unsigned installer automatically is a worse trade than doing it by hand.</Note>## Uninstall@@ -255,9 +203,7 @@ Remove it from **Settings → Installed apps**, or from a command line:msiexec /x BeaconEndpointAgent-<version>-x64.msi /qn```-Removal stops and deletes the service and takes the binaries away, but leaves-`%ProgramData%\Beacon\Endpoint` alone — collected telemetry is not something a package removal should-destroy, and an uninstall is often the first half of a reinstall. To remove that too:+Removal stops and deletes the service and takes the binaries away, but leaves `%ProgramData%\Beacon\Endpoint` alone. Collected telemetry is not something a package removal should destroy, and an uninstall is often the first half of a reinstall. To remove that too:```powershell title="Remove everything, including configuration and logs"$env:BEACON_PURGE = '1'@@ -275,14 +221,12 @@ beacon endpoint uninstall --system## Known gaps-Stated here rather than left to be discovered:-| Gap | Status ||---|---|-| The installer is unsigned | SmartScreen warns; verify the published `.sha256`. Authenticode signing is planned |-| `beacon endpoint update --apply` | Not supported on Windows; refuses rather than pretending. Waiting on signing |-| `beacon ci exec` | Captures intermittently on Windows ([#320](https://github.com/asymptote-labs/agent-beacon/issues/320)). The installed-hook path described on this page is unaffected |-| User-mode collectors | Do not restart and do not survive sign-out — no per-user service manager exists |+| The installer is unsigned | SmartScreen warns. Verify the published `.sha256`. Authenticode signing is planned |+| `beacon endpoint update --apply` | Not supported on Windows. It refuses rather than pretending. Waiting on signing |+| `beacon ci exec` | Captures intermittently on Windows ([#320](https://github.com/asymptote-labs/agent-beacon/issues/320)). The installed-hook path on this page is unaffected |+| User-mode collectors | Do not restart and do not survive sign-out, because Windows has no per-user service manager || Windows ARM | No package, because there is no ARM collector build || WSL | A Claude Code running inside WSL writes to the Linux filesystem and needs the Linux build, not this one |diff --git a/docs/runtimes/antigravity-cli.mdx b/docs/runtimes/antigravity-cli.mdxindex 0785cb85..a29b2cb9 100644--- a/docs/runtimes/antigravity-cli.mdx+++ b/docs/runtimes/antigravity-cli.mdx@@ -3,7 +3,7 @@ title: "Antigravity CLI"description: "Asymptote support details for Antigravity CLI endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Antigravity CLI through native hook payloads sent to `beacon-hooks`. Antigravity support was added in the endpoint agent in `v0.0.29`.@@ -50,7 +50,7 @@ Asymptote writes user-level Antigravity hooks to `~/.gemini/config/hooks.json` a| Prompt telemetry | Supported through `PreInvocation` and `UserPromptSubmit` hooks || Command, tool, and file telemetry | Supported for pre-tool, post-tool, invocation stop, command, failed edit, quoted path, diff, and file edit payloads where Antigravity exposes them || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; Antigravity hooks are installed separately in the logged-in user's context or project context |+| MDM deployment | Supported for the endpoint agent. Antigravity hooks are installed separately in the logged-in user's context or project context |Antigravity can invoke a pre-tool hook before its transcript file contains readable prompt text. Asymptote waits until the transcript is available before marking `prompt.submitted` as emitted, so the next hook in the same session can still record the prompt event.diff --git a/docs/runtimes/claude-code-ci.mdx b/docs/runtimes/claude-code-ci.mdxindex 9604bbd7..9dbe1ecf 100644--- a/docs/runtimes/claude-code-ci.mdx+++ b/docs/runtimes/claude-code-ci.mdx@@ -12,11 +12,11 @@ description: "Capture supported agent telemetry in CI with Asymptote"/></Frame>-## Runtime Overview+## Runtime overviewAsymptote can capture supported agent telemetry for a single CI job without installing a persistent endpoint service on the runner. The CI integration starts a temporary local collector, configures the selected agent harness, writes normalized CI runtime JSONL, and validates that events were captured before the job exits.-## How It Works+## How it worksUse `beacon ci exec` when your workflow runs the agent command directly:@@ -55,7 +55,7 @@ By default, Asymptote writes CI artifacts under `$RUNNER_TEMP/beacon` when `RUNN| Collector config | `$RUNNER_TEMP/beacon/otelcol.yaml` || Collector spool | `$RUNNER_TEMP/beacon/spool/otlp.jsonl` |-## Telemetry Coverage+## Telemetry coverageCI collection captures supported prompt, tool, command, file, lifecycle, and run context where the configured agent emits telemetry during the job. For example, Claude Code CI collection captures Claude Code events when the `claude` harness is configured. When `GITHUB_ACTIONS=true`, Asymptote also records GitHub Actions metadata such as workflow, run ID, commit, ref, and actor.@@ -100,7 +100,7 @@ See the sample workflow:- [Claude Code telemetry workflow](https://github.com/Asymptote-Labs/agent-beacon/blob/main/examples/github-actions/claude-code-telemetry.yml)- [Claude Code Security Review session workflow](https://github.com/Asymptote-Labs/agent-beacon/blob/main/examples/github-actions/claude-security-review-session.yml)-## Upload To Object Storage+## Upload to object storageUse `--upload` when the completed `runtime.jsonl` should be handed off through object storage after validation.@@ -146,7 +146,7 @@ See the sample workflows:- [GCS upload telemetry workflow](https://github.com/Asymptote-Labs/agent-beacon/blob/main/examples/github-actions/gcs-upload-telemetry.yml)- [S3 and GCS upload telemetry workflow](https://github.com/Asymptote-Labs/agent-beacon/blob/main/examples/github-actions/s3-gcs-upload-telemetry.yml)-## Validation Behavior+## Validation behaviorBy default, `beacon ci exec` fails the step when telemetry validation fails. Set `--require-telemetry=false` or the action input `require-telemetry: "false"` when telemetry health should warn but not gate the child command result.diff --git a/docs/runtimes/claude-code-cloud-agents.mdx b/docs/runtimes/claude-code-cloud-agents.mdxindex ba91545e..ca2593dc 100644--- a/docs/runtimes/claude-code-cloud-agents.mdx+++ b/docs/runtimes/claude-code-cloud-agents.mdx@@ -12,7 +12,7 @@ description: "Capture Claude Code cloud agent telemetry and forward cloud-agent/></Frame>-## Integration Overview+## OverviewUse this integration to capture Claude Code cloud-agent activity and upload eachsession log to your own Google Cloud Storage or Amazon S3 bucket. It is meant@@ -29,7 +29,7 @@ sandbox.production cloud-agent telemetry ingest at scale.</Info>-## Overview+## How it worksClaude Code Cloud Agents run in Anthropic's cloud environment, so Beacon cannotuse the long-running endpoint agent that local installs use. Instead, the setup@@ -98,7 +98,7 @@ For S3, authenticate the AWS CLI:aws sts get-caller-identity```-## 1. Create the Upload Path+## 1. Create the upload pathChoose GCS or S3 for the cloud-agent session logs.@@ -242,7 +242,7 @@ AWS_SECRET_ACCESS_KEY=<secret-access-key-from-setup><img src="/images/claude-code-on-the-web/claude-env-settings.png" alt="Claude Code cloud environment settings showing custom network domains, Beacon environment variables, and a setup script." /></Frame>-## 3. Add the Setup Script+## 3. Add the setup scriptGenerate the setup script for your Beacon release:@@ -264,7 +264,7 @@ The script:`print-setup --version`.</Tip>-## 4. Run a Cloud Agent Task+## 4. Run a cloud agent taskStart a Claude Code cloud agent task that uses tools. You can start the taskfrom the Claude app on your phone or from the Claude Code web application. For@@ -278,7 +278,7 @@ Read the README, run pwd && ls, create a tiny temporary markdown note under /tmp<img src="/images/claude-code-on-the-web/session-init-and-task-output.png" alt="Claude Code cloud agent session showing setup completed, a README task, shell command activity, and a temporary note creation." /></Frame>-## 5. Verify Upload+## 5. Verify uploadFor GCS, list the uploaded session objects:@@ -326,7 +326,7 @@ run.provider=claude_code_webrun.run_id=cse_...```-## Security Note+## Security noteThe self-serve GCS flow above creates a dedicated service account scoped toobject uploads for one bucket. The S3 flow creates a dedicated IAM user scopeddiff --git a/docs/runtimes/claude-code.mdx b/docs/runtimes/claude-code.mdxindex 294f0d67..f48df920 100644--- a/docs/runtimes/claude-code.mdx+++ b/docs/runtimes/claude-code.mdx@@ -3,7 +3,7 @@ title: "Claude Code"description: "Asymptote support details for Claude Code endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Claude Code through local OpenTelemetry export to Asymptote's localhost collector, with optional hook telemetry for richer lifecycle and tool activity.diff --git a/docs/runtimes/claude-cowork.mdx b/docs/runtimes/claude-cowork.mdxindex 4d466ec0..599aad85 100644--- a/docs/runtimes/claude-cowork.mdx+++ b/docs/runtimes/claude-cowork.mdx@@ -3,7 +3,7 @@ title: "Claude Cowork"description: "Asymptote support details for Claude Cowork endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Claude Cowork through admin-configured OpenTelemetry from Anthropic's service.diff --git a/docs/runtimes/cline.mdx b/docs/runtimes/cline.mdxindex de667b02..4f434180 100644--- a/docs/runtimes/cline.mdx+++ b/docs/runtimes/cline.mdx@@ -3,7 +3,7 @@ title: "Cline"description: "Asymptote support details for Cline endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports [Cline](https://cline.bot/) through a managed local plugin that invokes `beacon-hooks`.@@ -20,7 +20,7 @@ Before enabling Cline telemetry, make sure:## Collection path-Asymptote installs an owned Cline plugin at `~/.cline/plugins/beacon.ts` for user-level hooks or `./.cline/plugins/beacon.ts` for project-level hooks. Cline auto-discovers plugin files in those directories, so no plugin registry command is required — which is also why the install works for the VS Code and JetBrains hosts, neither of which ships a `cline` executable.+Asymptote installs an owned Cline plugin at `~/.cline/plugins/beacon.ts` for user-level hooks or `./.cline/plugins/beacon.ts` for project-level hooks. Cline auto-discovers plugin files in those directories, so no plugin registry command is required. That is also why the install works for the VS Code and JetBrains hosts, neither of which ships a `cline` executable.The plugin forwards `beforeRun`, `beforeTool`, `afterTool`, and `afterRun` hook payloads to Asymptote's hook adapter. It spawns the adapter directly with an argument vector rather than through a shell, so the same plugin works unchanged on macOS, Linux, and Windows.@@ -51,15 +51,17 @@ beacon endpoint hooks install --harness cline| File telemetry | `read_file`, `list_files`, `search_files`, and `list_code_definition_names` reads; `write_to_file` and `replace_in_file` modifications with diff hash and byte count || MCP telemetry | `use_mcp_tool` and `access_mcp_resource` normalized as MCP tool activity || Model and usage | Provider-qualified model, token counts, cache reads, and runtime-reported cost, recorded once per task |-| Approval telemetry | Not supported — see Known gaps |+| Approval telemetry | Not supported. See [Known gaps](#known-gaps) || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; Cline plugins are installed separately in the logged-in user's context |+| MDM deployment | Supported for the endpoint agent. Cline plugins are installed separately in the logged-in user's context |Cline addresses files relative to the workspace root. Beacon resolves those paths against the workspace before writing them, so a Cline file event is comparable with the same file seen through another runtime and matches threat rules written against absolute paths. A path that is already absolute is left alone, and a relative path with no resolvable workspace root stays relative rather than being joined to a guessed root.-A cancelled task ends rather than fails. Cline fires its cancel hook for the cleanup that follows someone stopping or abandoning a task, so Beacon records `session.ended` at info severity with `session.cancel_reason` set, not `session.error` — otherwise every deliberate stop would count as an incident in error rollups and alerting. A cancelled task still reports the tokens it spent. Cancels and failures reach Beacon two ways: the file-based hooks name them in the hook itself, and the plugin reports them as a status on its single run-completion handler. Both are read, so the distinction holds on the surface Beacon actually installs; a run that reports no recognized outcome is recorded as a completion.+A cancelled task ends rather than fails. Cline fires its cancel hook for the cleanup that follows someone stopping or abandoning a task, so Beacon records `session.ended` at info severity with `session.cancel_reason` set, not `session.error`. Otherwise every deliberate stop would count as an incident in error rollups and alerting. A cancelled task still reports the tokens it spent.-Token usage is recorded at task end only. Beacon's token rollups sum `gen_ai.usage` across events, so reporting the same tokens at a per-model-call boundary as well would double every Cline task's totals. Cost is recorded only as Cline reports it; Beacon never derives cost from a local price table.+Cancels and failures reach Beacon two ways: the file-based hooks name them in the hook itself, and the plugin reports them as a status on its run-completion handler. Both are read, so the distinction holds on the surface Beacon installs. A run that reports no recognized outcome is recorded as a completion.++Token usage is recorded at task end only. Beacon's token rollups sum `gen_ai.usage` across events, so reporting the same tokens at a per-model-call boundary would double every Cline task's totals. Cost is recorded only as Cline reports it. Beacon never derives cost from a local price table.## Data handling@@ -69,8 +71,8 @@ The plugin flattens Cline's live hook context before sending it, dropping functi## Known gaps-- **Approval decisions are not recorded.** Cline requires approval for actions by default, but the documented hook context does not carry the approval state, so Beacon does not synthesize an approval decision from a tool call. The forwarded payload is preserved, so approval telemetry can be added without changing what is already collected.-- **No enforcement.** Cline's `beforeTool` hook can cancel a tool call, and Beacon's plugin never does. Enforcement remains behind the optional, off-by-default policy-provider seam (`BEACON_POLICY_PROVIDER`), which is not wired to Cline.+- **Approval decisions are not recorded.** Cline requires approval for actions by default, but the documented hook context does not carry the approval state, so Beacon does not synthesize an approval decision from a tool call. The forwarded payload is preserved, so approval telemetry can be added later without changing what is already collected.+- **No enforcement.** Cline's `beforeTool` hook can cancel a tool call, and Beacon's plugin never does. Enforcement stays behind the optional, off-by-default policy provider seam (`BEACON_POLICY_PROVIDER`), which is not wired to Cline.## Deployment notesdiff --git a/docs/runtimes/codex-cli.mdx b/docs/runtimes/codex-cli.mdxindex f07da235..24367a66 100644--- a/docs/runtimes/codex-cli.mdx+++ b/docs/runtimes/codex-cli.mdx@@ -3,7 +3,7 @@ title: "Codex CLI"description: "Asymptote support details for Codex CLI endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Codex CLI runtime telemetry through local OTLP logs and token usage metrics, with optional raw Codex spans for troubleshooting. Codex hooks can also trigger endpoint inventory heartbeats without replacing the OTLP runtime path.diff --git a/docs/runtimes/cursor-cloud-agents.mdx b/docs/runtimes/cursor-cloud-agents.mdxindex 981a6469..6aa63050 100644--- a/docs/runtimes/cursor-cloud-agents.mdx+++ b/docs/runtimes/cursor-cloud-agents.mdx@@ -3,7 +3,7 @@ title: "Cursor Cloud Agents"description: "Capture Cursor cloud agent telemetry and forward cloud-agent runtime logs to customer-managed Google Cloud Storage or Amazon S3"----## Integration Overview+## OverviewUse this integration to capture Cursor cloud-agent activity and upload eachsession log to your own Google Cloud Storage or Amazon S3 bucket. It is meant@@ -20,7 +20,7 @@ binaries in the Cursor cloud sandbox.production cloud-agent telemetry ingest at scale.</Info>-## Overview+## How it worksCursor Cloud Agents run in Cursor's cloud environment, so Beacon cannot use thelong-running endpoint agent that local installs use. Instead, commit@@ -93,7 +93,7 @@ gcloud auth logingcloud config set project <your-gcp-project>```-## 1. Create the Object Storage Upload Path+## 1. Create the object storage upload pathChoose GCS or S3 for the cloud-agent session logs.@@ -231,7 +231,7 @@ github.com*.githubusercontent.com```-## 3. Commit Cursor Project Hooks+## 3. Commit Cursor project hooksCursor Cloud Agents load project hooks from `.cursor/hooks.json` at repositorycheckout and task start. Generate the hook file locally, commit it, and push it@@ -254,7 +254,7 @@ git pushavailable when the agent starts.</Warning>-## 4. Add the Setup Script+## 4. Add the setup scriptGenerate the setup script for your Beacon release:@@ -283,7 +283,7 @@ script:`print-setup --version`.</Tip>-## 5. Run a Cloud Agent Task+## 5. Run a cloud agent taskStart a Cursor cloud agent task that uses tools so the environment becomeswritable and project hooks become active. For example:@@ -317,7 +317,7 @@ Do not inspect files or run tools. Reply exactly: PROMPT CAPTURE TEST COMPLETEfor the current platform support list.</Note>-## 6. Verify Object Storage Upload+## 6. Verify object storage uploadFor GCS, list the uploaded session objects:@@ -383,7 +383,7 @@ harness.name=cursorrun.provider=cursor_cloud```-## Security Note+## Security noteThe self-serve flows create a dedicated GCS service account or AWS IAM userscoped to object uploads, then store its credentials in the Cursor clouddiff --git a/docs/runtimes/cursor.mdx b/docs/runtimes/cursor.mdxindex 06ae5a11..426a0c29 100644--- a/docs/runtimes/cursor.mdx+++ b/docs/runtimes/cursor.mdx@@ -3,7 +3,7 @@ title: "Cursor"description: "Asymptote support details for Cursor endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Cursor through native hook payloads sent to `beacon-hooks`.For provider-managed Cursor cloud sessions, see@@ -52,7 +52,7 @@ beacon endpoint hooks install --harness cursor --level project| Agent reasoning telemetry | Supported for local Cursor through `afterAgentThought` hooks. Each completed thinking block is recorded as an `agent.reasoning` event carrying the reasoning text in the OpenTelemetry GenAI output-messages shape (`gen_ai.output.messages` with a `reasoning` part), plus a `content` marker with the original text's hash and byte count. Reasoning is only available for models/modes where Cursor exposes visible thinking text. || Repository and branch context | Events include the workspace path as `repository`, and `branch` is resolved from the workspace's local git checkout (`.git/HEAD`) when Cursor does not supply one; disable local git resolution with `BEACON_DISABLE_GIT_METADATA=1`. || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; Cursor hooks are installed separately in the logged-in user's context. |+| MDM deployment | Supported for the endpoint agent. Cursor hooks are installed separately in the logged-in user's context |## Deployment notesdiff --git a/docs/runtimes/devin-cloud-agents.mdx b/docs/runtimes/devin-cloud-agents.mdxindex 717b920e..9e29d817 100644--- a/docs/runtimes/devin-cloud-agents.mdx+++ b/docs/runtimes/devin-cloud-agents.mdx@@ -3,28 +3,28 @@ title: "Devin Cloud Agents"description: "Capture autonomous Devin Cloud agent telemetry org-wide with the Beacon CLI and forward it to customer-managed storage or a SIEM"----## Integration Overview+## OverviewUse this integration to capture telemetry from **autonomous Devin Cloud agents**(sessions at [app.devin.ai](https://app.devin.ai)) for every user in yourorganization, using the Beacon CLI. Unlike the [Devin CLI](/runtimes/devin) and-[Devin Desktop](/runtimes/devin-desktop) integrations — which capture telemetry-through local hooks — the autonomous Devin Cloud agent does not run the Devin+[Devin Desktop](/runtimes/devin-desktop) integrations, which capture telemetry+through local hooks, the autonomous Devin Cloud agent does not run the Devinhook engine. Beacon instead pulls session activity from the Devin**organization API** with a single command you run centrally.<Info>If you're interested in leveraging this telemetry ingest across your- enterprise, [Asymptote Managed](/asymptote-managed) is designed for+ enterprise, [Asymptote Managed](/deployment/managed) is designed forproduction cloud-agent telemetry ingest at scale.</Info>-## Overview+## How it works`beacon cloud devin pull` authenticates to the Devin v3 organization API with anorganization **service key** and enumerates every user's cloud sessions. It mapseach session and its messages into Beacon endpoint events, writes them to the-local runtime JSONL, and — when GCS is configured — uploads a per-session+local runtime JSONL, and, when GCS is configured, uploads a per-sessionsnapshot to your bucket. Because the service key is organization-scoped, onecentral runner captures all of your users' Devin Cloud sessions; there isnothing to install per user, per repository, or per session.@@ -62,8 +62,8 @@ Beacon uses the Devin session id as the `run_id` and the Devin user id as- Beacon CLI `v0.0.67` or later.- A Devin **organization service key** (`cog_` prefix) and your **organizationid** (`org-...`). Create a service user with session-read access under Devin- **Settings → Service Users**. A Teams-tier plan is sufficient — an Enterprise- plan is not required.+ **Settings → Service Users**. A Teams-tier plan is enough; an Enterprise plan+ is not required.- A host (workstation, VM, or CI runner) to run the connector centrally, on aschedule or continuously.- For GCS upload: `gcloud` installed and authenticated, and a Google Cloud@@ -79,7 +79,7 @@ brew upgrade beaconbeacon version```-## 1. Create the GCS Upload Path+## 1. Create the GCS upload pathSkip this step if you only want events in the local runtime log (for example toforward to a SIEM from the runner). To archive per-session snapshots to your own@@ -103,7 +103,7 @@ beacon cloud gcs setup \Copy the printed `BEACON_CLOUD_GCS_*` values. Treat`BEACON_CLOUD_GCS_CREDENTIALS_B64` as a sensitive credential.-## 2. Provide Devin Credentials+## 2. Provide Devin credentialsOn the central runner, export the organization service key and id:@@ -114,11 +114,11 @@ export DEVIN_ORG_ID="org-…your_organization…"<Warning>The organization service key can read sessions across your whole org. Keep it- on one controlled runner — never distribute it to individual user machines or+ on one controlled runner. Never distribute it to individual user machines oragent sandboxes.</Warning>-## 3. Pull Devin Cloud Telemetry+## 3. Pull Devin cloud telemetryPreview the mapped events without writing or uploading anything:@@ -139,7 +139,7 @@ beacon cloud devin pull --watch --interval 30s```When the `BEACON_CLOUD_GCS_*` variables from step 1 are exported, each changed-session's snapshot is also uploaded to your bucket. Re-runs are idempotent —+session's snapshot is also uploaded to your bucket. Re-runs are idempotent:events are deduplicated by their Devin event id, and unchanged sessions areskipped. Use `--full-resync` to re-fetch and re-upload every session (for abackfill, or after enabling GCS on an existing runner).@@ -150,7 +150,7 @@ backfill, or after enabling GCS on an existing runner).cron job / scheduled CI workflow on the central runner.</Tip>-## 4. Verify the Upload+## 4. Verify the upload```bashgcloud storage ls --recursive "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/provider=devin_cloud/"@@ -188,7 +188,7 @@ log. Events carry `run.actor=<user_id>` for per-user attribution. See[Google Cloud Storage forwarding](/siem-forwarding-gcs) and the other SIEMforwarding guides for the available destinations.-## Security Note+## Security noteThis flow keeps your Devin organization service key and (optionally) aGCS uploader credential on a single controlled runner. Beacon's use of the Devin@@ -235,7 +235,7 @@ in-progress session shows `session.started`, `prompt.submitted`, and<Card title="Google Cloud Storage forwarding" icon="database" href="/siem-forwarding-gcs">Review local endpoint GCS forwarding for persistent deployments.</Card>- <Card title="Asymptote Managed" icon="cloud" href="/asymptote-managed">+ <Card title="Asymptote Managed" icon="cloud" href="/deployment/managed">Use managed secure ingest for production enterprise cloud-agent telemetry.</Card></Columns>diff --git a/docs/runtimes/devin-desktop.mdx b/docs/runtimes/devin-desktop.mdxindex a6fc14ad..5a453615 100644--- a/docs/runtimes/devin-desktop.mdx+++ b/docs/runtimes/devin-desktop.mdx@@ -3,7 +3,7 @@ title: "Devin Desktop"description: "Asymptote support details for Devin Desktop endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Devin Desktop through Cascade/Windsurf-compatible hook payloads sent to `beacon-hooks`.@@ -54,7 +54,7 @@ beacon endpoint install --harness claude,codex,devin-desktop| Prompt telemetry | Supported through Cascade prompt hooks || Command, tool, and file telemetry | Supported for prompt, command, MCP tool, file read, and file write telemetry where Cascade/Windsurf hook payloads are available || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; Devin Desktop hooks are installed separately in the logged-in user's context or project context |+| MDM deployment | Supported for the endpoint agent. Devin Desktop hooks are installed separately in the logged-in user's context or project context |## Deployment notesdiff --git a/docs/runtimes/devin.mdx b/docs/runtimes/devin.mdxindex 1e201017..ab6c18e1 100644--- a/docs/runtimes/devin.mdx+++ b/docs/runtimes/devin.mdx@@ -3,7 +3,7 @@ title: "Devin CLI"description: "Asymptote support details for Devin CLI endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Devin CLI through native Devin hook payloads sent to `beacon-hooks`.@@ -48,7 +48,7 @@ beacon endpoint hooks install --harness devin-cli --level project| Prompt telemetry | Supported through `UserPromptSubmit` hooks || Command, tool, and file telemetry | Supported for session, prompt, pre-tool, post-tool, permission request, stop, session-end, approval, and file telemetry where Devin CLI exposes payloads || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; Devin CLI hooks are installed separately in the logged-in user's context or project context |+| MDM deployment | Supported for the endpoint agent. Devin CLI hooks are installed separately in the logged-in user's context or project context |## Deployment notesdiff --git a/docs/runtimes/factory-droid.mdx b/docs/runtimes/factory-droid.mdxindex 63465f8b..b5be4aeb 100644--- a/docs/runtimes/factory-droid.mdx+++ b/docs/runtimes/factory-droid.mdx@@ -3,7 +3,7 @@ title: "Factory Droid"description: "Asymptote support details for Factory Droid endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Factory Droid through an OTLP HTTP launch environment plus optional hook telemetry.@@ -46,7 +46,7 @@ beacon endpoint hooks install --harness factory| Prompt telemetry | Supported through `UserPromptSubmit` hooks || Command, tool, and file telemetry | Supported for session, write/edit/create tool use, stop, session-end, and available OTLP telemetry || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; Factory launch environment and user/project hooks are managed in the user's Droid context |+| MDM deployment | Supported for the endpoint agent. Factory launch environment and user/project hooks are managed in the user's Droid context |## Deployment notesdiff --git a/docs/runtimes/gemini-cli.mdx b/docs/runtimes/gemini-cli.mdxindex 00413160..6972185b 100644--- a/docs/runtimes/gemini-cli.mdx+++ b/docs/runtimes/gemini-cli.mdx@@ -3,7 +3,7 @@ title: "Gemini CLI"description: "Asymptote support details for Gemini CLI endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Gemini CLI through opt-in local OTLP logs, traces, and metrics.diff --git a/docs/runtimes/github-copilot-cli.mdx b/docs/runtimes/github-copilot-cli.mdxindex e0a973ba..e5680cdc 100644--- a/docs/runtimes/github-copilot-cli.mdx+++ b/docs/runtimes/github-copilot-cli.mdx@@ -3,7 +3,7 @@ title: "GitHub Copilot CLI"description: "Asymptote support details for GitHub Copilot CLI endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports GitHub Copilot CLI through MDM-managed OpenTelemetry export to the local OTLP HTTP receiver.@@ -48,7 +48,7 @@ If your deployment intentionally captures GenAI message content from Copilot telexport OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="true"```-For a one-command local validation flow, see [Test GitHub Copilot CLI telemetry](/guides/local-testing/events#test-github-copilot-cli-telemetry).+For a one-command local validation flow, see [Test GitHub Copilot CLI telemetry](/guides/local-testing/events#4-test-github-copilot-cli-telemetry).## Telemetry coverage@@ -57,7 +57,7 @@ For a one-command local validation flow, see [Test GitHub Copilot CLI telemetry]| Prompt telemetry | Supported from Copilot chat spans when exported over OTLP HTTP || Command, tool, and file telemetry | Supported for session activity, tool invocation, and permission or approval-like spans emitted by Copilot CLI || Local JSONL and dashboard | Supported after events reach the local collector |-| MDM deployment | Supported for the endpoint agent; Copilot launch-environment configuration stays under MDM or customer policy control |+| MDM deployment | Supported for the endpoint agent. Copilot launch-environment configuration stays under MDM or customer policy control |## Deployment notesdiff --git a/docs/runtimes/grok-build.mdx b/docs/runtimes/grok-build.mdxindex 52e27624..2e913111 100644--- a/docs/runtimes/grok-build.mdx+++ b/docs/runtimes/grok-build.mdx@@ -3,7 +3,7 @@ title: "Grok Build"description: "Asymptote support details for Grok Build endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Grok Build through native hook payloads sent to `beacon-hooks`.@@ -48,7 +48,7 @@ beacon endpoint hooks install --harness grok --level project| Prompt telemetry | Supported through `UserPromptSubmit` hooks || Command, tool, and file telemetry | Supported for session, prompt, pre-tool, post-tool, failed tool, stop, session-end, command, and file telemetry where Grok exposes payloads || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; Grok hooks are installed separately in the logged-in user's context or project context |+| MDM deployment | Supported for the endpoint agent. Grok hooks are installed separately in the logged-in user's context or project context |## Deployment notesdiff --git a/docs/runtimes/hermes-agent.mdx b/docs/runtimes/hermes-agent.mdxindex 5f3b2b6b..951e75ad 100644--- a/docs/runtimes/hermes-agent.mdx+++ b/docs/runtimes/hermes-agent.mdx@@ -3,7 +3,7 @@ title: "Hermes Agent"description: "Asymptote support details for Hermes Agent endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Hermes Agent through shell hook payloads sent to `beacon-hooks`.@@ -46,7 +46,7 @@ Hermes Agent hooks support user-level config only. Project-level installs are re| Approval telemetry | Supported for Hermes approval request and response hooks, including allow, deny, timeout, and unknown decisions || Session and subagent telemetry | Supported for session lifecycle events and subagent stop metadata where Hermes exposes role, status, summary, and duration || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; Hermes hooks are installed separately in the logged-in user's context |+| MDM deployment | Supported for the endpoint agent. Hermes hooks are installed separately in the logged-in user's context |## Deployment notesdiff --git a/docs/runtimes/index.mdx b/docs/runtimes/index.mdxindex 0be94c67..3d73ece7 100644--- a/docs/runtimes/index.mdx+++ b/docs/runtimes/index.mdx@@ -3,7 +3,7 @@ title: "Runtime Surface Overview"description: "Asymptote agent harness support overview and runtime-specific pages"----## Support Matrix+## OverviewAsymptote supports multiple [runtime surfaces](/concepts/core-concepts#runtime-surface) because each [agent harness](/concepts/core-concepts#agent-harness) exposes telemetry differently. The runtime support model applies to both Asymptote Open Source and Asymptote Managed: Open Source collects and normalizes supported local, CI, and cloud-agent telemetry, while Managed adds hosted ingest, visibility, and governance on top of the same surfaces.@@ -15,7 +15,7 @@ These integrations are grouped by where the agent runs and how telemetry is coll## Support matrix-### Local Coding Agent Harnesses+### Local coding agent harnesses| Agent harness | Collection path | Telemetry coverage ||----------------|-----------------|--------------------|@@ -31,11 +31,11 @@ These integrations are grouped by where the agent runs and how telemetry is coll| [GitHub Copilot CLI](/runtimes/github-copilot-cli) | MDM-managed OTLP HTTP | Prompt, session, tool, and approval-like activity emitted through Copilot CLI spans || [Grok Build](/runtimes/grok-build) | Native hooks | Session, prompt, pre-tool, post-tool, failed tool, stop, session-end, command, and file telemetry || [OpenCode](/runtimes/opencode) | Managed plugin hooks | Chat messages, session events, command execution, permission activity, diffs, and errors |-| [Pi](/runtimes/pi) | Managed extension hooks | Discovery and harness attribution today; the managed extension that collects prompt, tool, command, and file telemetry is not shipped yet |+| [Pi](/runtimes/pi) | Managed extension hooks | Session lifecycle, prompts, tool lifecycle, commands including operator `!` commands, file reads and edits with the unified patch, agent reasoning, and token usage || [Qwen Code](/runtimes/qwen-code) | Native hooks | Session, prompt, pre-tool, post-tool, failed tool, permission request, subagent, stop, session-end, command, and file telemetry || [VS Code](/runtimes/vscode) | Copilot Chat OTel plus optional preview hooks | Copilot session, prompt, model, and tool activity through OTel; optional hooks for extra lifecycle and cross-agent detail |-### Local Knowledge Worker Agent Harnesses+### Local knowledge worker agent harnesses| Agent harness | Collection path | Telemetry coverage ||----------------|-----------------|--------------------|@@ -43,13 +43,13 @@ These integrations are grouped by where the agent runs and how telemetry is coll| [Hermes Agent](/runtimes/hermes-agent) | Shell hooks | Prompt, observed tool, command, file, approval request and response, session lifecycle, and subagent stop telemetry || [OpenClaw Gateway](/runtimes/openclaw-gateway) | Gateway-configured OTLP/HTTP | OTLP logs, traces, and metrics from the Gateway diagnostics plugin |-### CI Harnesses+### CI harnesses| Harness | Collection path | Telemetry coverage ||---------|-----------------|--------------------|| [CI agent telemetry](/runtimes/claude-code-ci) | Temporary local collector through `beacon ci exec` or `beacon ci start` / `beacon ci finish` | Supported agent prompt, tool, command, file, and run context where emitted during the job |-### Cloud Agent Harnesses and SDKs+### Cloud agent harnesses and SDKs| Cloud surface | Collection path | Telemetry coverage ||---------------|-----------------|--------------------|@@ -62,30 +62,32 @@ These integrations are grouped by where the agent runs and how telemetry is coll## Deployment notes-Local agent harnesses need the endpoint agent installed on the machine they run on. Use the native-package for that platform, which installs and starts everything in one step:+Local agent harnesses need the endpoint agent installed on the machine they run on. Use the native package for that platform, which installs and starts everything in one step:-<Columns cols={2}>+<Columns cols={3}><Card title="macOS" icon="apple" href="/platforms/macos">- Signed, notarized `.pkg` — Jamf Pro, Fleet, Rippling, or manual.+ Signed, notarized `.pkg` for Jamf Pro, Fleet, Rippling, or manual install.</Card><Card title="Linux" icon="linux" href="/platforms/linux">`.deb` and `.rpm` for amd64 and arm64.</Card>+ <Card title="Windows" icon="windows" href="/platforms/windows">+ `.msi` for x64, installed as a Windows service.+ </Card></Columns>-Either package:+Each package installs the endpoint agent, starts the [local collector](/concepts/core-concepts#local-collector) as a service, and configures the installing user's supported agent runtimes to export to it. Paths differ per platform:++| | macOS | Linux | Windows |+|---|---|---|---|+| Binaries | `/opt/beacon` | `/opt/beacon` | `%ProgramFiles%\Beacon\bin` |+| System config | `/Library/Application Support/Beacon/Endpoint` | `/etc/beacon/endpoint` | `%ProgramData%\Beacon\Endpoint` |+| Service | LaunchDaemon | systemd unit | `BeaconCollector` Windows service |+| Runtime log | `/var/log/beacon-agent/runtime.jsonl` | `/var/log/beacon-agent/runtime.jsonl` | `%ProgramData%\Beacon\Endpoint\logs\runtime.jsonl` |-- Installs the endpoint agent under `/opt/beacon`-- Creates system endpoint configuration — `/Library/Application Support/Beacon/Endpoint` on macOS,- `/etc/beacon/endpoint` on Linux-- Starts the [local collector](/concepts/core-concepts#local-collector) as a service — a LaunchDaemon- on macOS, a systemd unit on Linux-- Writes [endpoint events](/concepts/core-concepts#endpoint-event) to `/var/log/beacon-agent/runtime.jsonl`-- Configures the installing user's supported agent runtimes to export to the local collector+MDM assets, meaning Jamf Pro Extension Attributes, Fleet osquery queries, and Rippling deployment, are macOS only. On Linux and Windows, deploy the package with whatever configuration management you already run.-MDM assets — Jamf Pro Extension Attributes, Fleet osquery queries, Rippling deployment — are macOS-only. On Linux, deploy the `.deb` or `.rpm` with whatever configuration management you already run.+### Enterprise runtime configuration| Runtime | Enterprise configuration ||---------|--------------------------|@@ -94,15 +96,15 @@ only. On Linux, deploy the `.deb` or `.rpm` with whatever configuration manageme| Factory Droid | Configure launch environment with `OTEL_TELEMETRY_ENDPOINT=http://127.0.0.1:4318`. Asymptote discovers the runtime and validates the endpoint but does not edit shell profiles or launch environments. || OpenClaw Gateway | Configure OTLP in OpenClaw. Use [`beacon endpoint integrations openclaw`](/cli/openclaw) to print local Gateway settings and validate events. |-Install Antigravity CLI, Claude Code, Cline, Codex CLI inventory hooks, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, OpenCode, and optional VS Code hooks separately in the logged-in user's context when you need richer hook telemetry or inventory heartbeat triggers.+Install hooks separately in the logged-in user's context when you need richer hook telemetry or inventory heartbeat triggers. This applies to Antigravity CLI, Claude Code, Cline, Codex CLI inventory hooks, Cursor, Devin CLI, Devin Desktop, Factory Droid, Grok Build, Hermes Agent, OpenCode, Pi, Qwen Code, and the optional VS Code hooks.If a system collector is running while the CLI is reading the default per-user log, `beacon endpoint status` and the local dashboard surface a runtime-log source warning so you can tell where OTLP events are being written.## Related<Columns cols={2}>- <Card title="Agent harness integrations" icon="list-check" href="/runtimes">- Return to the support overview.+ <Card title="Core concepts" icon="book" href="/concepts/core-concepts">+ Runtime surfaces, agent harnesses, and endpoint events.</Card><Card title="Agent harness integration model" icon="plug" href="/runtimes/integration-model">See how Asymptote discovers and configures each runtime.diff --git a/docs/runtimes/integration-model.mdx b/docs/runtimes/integration-model.mdxindex 0be77a10..b6d5993a 100644--- a/docs/runtimes/integration-model.mdx+++ b/docs/runtimes/integration-model.mdx@@ -3,7 +3,7 @@ title: "Agent Harness Integration Model"description: "How Beacon discovers, validates, and configures supported agent harnesses"----## Integration Model+## Integration modelBeacon supports multiple [runtime surfaces](/concepts/core-concepts#runtime-surface) because each [agent harness](/runtimes) exposes telemetry differently. Supported harnesses use local OpenTelemetry configuration, admin- or gateway-configured OTLP export, hook adapters, or a combination of those paths.diff --git a/docs/runtimes/openclaw-gateway.mdx b/docs/runtimes/openclaw-gateway.mdxindex 992bcdf0..9419a744 100644--- a/docs/runtimes/openclaw-gateway.mdx+++ b/docs/runtimes/openclaw-gateway.mdx@@ -3,7 +3,7 @@ title: "OpenClaw Gateway"description: "Asymptote support details for OpenClaw Gateway endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports OpenClaw Gateway through gateway-configured OTLP/HTTP export.@@ -42,7 +42,7 @@ OpenClaw Gateway is not hook-based.| Prompt telemetry | Disabled by default unless OpenClaw `captureContent` settings are explicitly enabled || Command, tool, and file telemetry | Supported for OTLP logs, traces, and metrics emitted by the Gateway diagnostics plugin || Local JSONL and dashboard | Supported after events reach the collector |-| MDM deployment | Supported for the endpoint agent; Gateway diagnostics configuration is managed in OpenClaw |+| MDM deployment | Supported for the endpoint agent. Gateway diagnostics configuration is managed in OpenClaw |## Deployment notesdiff --git a/docs/runtimes/opencode.mdx b/docs/runtimes/opencode.mdxindex ebc94f00..9e10da26 100644--- a/docs/runtimes/opencode.mdx+++ b/docs/runtimes/opencode.mdx@@ -3,7 +3,7 @@ title: "OpenCode"description: "Asymptote support details for OpenCode endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports OpenCode through a managed local plugin that invokes `beacon-hooks`.@@ -20,8 +20,7 @@ Before enabling OpenCode telemetry, make sure:Asymptote installs an owned OpenCode plugin at `~/.config/opencode/plugins/beacon.ts` for user-level hooks or `./.opencode/plugins/beacon.ts` for project-level hooks. The plugin forwards supported OpenCode hook payloads to Asymptote's hook adapter.-The integration is plugin-based. OpenCode native OTLP is not configured or-required by Beacon.+The integration is plugin-based. OpenCode's native OTLP export is neither configured nor required by Beacon.## Discovery and status@@ -47,25 +46,17 @@ beacon endpoint hooks install --harness opencode| Command telemetry | Model-invoked Bash/shell tools plus successful OpenCode custom commands || File telemetry | Read/search/glob and write/edit/patch activity with agent-derived paths; empty session diffs are ignored || Web and MCP telemetry | Web tool arguments/results and normalized MCP server/tool/resource context |-| Approval telemetry | Requests plus `once`, `always`, and `reject` replies normalized as requested/allowed/denied |+| Approval telemetry | Requests plus `once`, `always`, and `reject` replies, normalized as requested, allowed, and denied || Model and usage | Provider/model, finish reason, token usage, cache usage, reasoning tokens, and runtime-reported cost || Session telemetry | Create, busy/idle/end, retry, and error boundaries || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; OpenCode plugins are installed separately in the logged-in user's context |+| MDM deployment | Supported for the endpoint agent. OpenCode plugins are installed separately in the logged-in user's context |## Data handling-OpenCode prompts, completed assistant text and reasoning, tool arguments/results,-commands, command output, paths, and diffs are retained in local or-customer-controlled logs. Beacon applies local secret redaction and per-string-limits before writing. Each content-bearing event includes a hash and byte count-for the original value. Events that exceed the 64 KiB limit drop raw and-retained content while preserving stable metadata and set `field_truncated`.--The plugin uses OpenCode session, message, part, permission request, and tool-call identifiers for correlation. It does not create file events without an-agent-derived path, so object-storage ingestion paths are not treated as files-the agent touched.+OpenCode prompts, completed assistant text and reasoning, tool arguments and results, commands, command output, paths, and diffs are retained in local or customer-controlled logs. Beacon applies local secret redaction and per-string limits before writing. Each content-bearing event includes a hash and byte count for the original value. Events over the 64 KiB limit drop raw and retained content, preserve stable metadata, and set `field_truncated`.++The plugin uses OpenCode session, message, part, permission request, and tool call identifiers for correlation. It does not create file events without an agent-derived path, so object-storage ingestion paths are not treated as files the agent touched.## Deployment notesdiff --git a/docs/runtimes/pi.mdx b/docs/runtimes/pi.mdxindex f1ecfd6b..c1b8f0fc 100644--- a/docs/runtimes/pi.mdx+++ b/docs/runtimes/pi.mdx@@ -3,13 +3,11 @@ title: "Pi"description: "Asymptote support details for Pi endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports [Pi](https://pi.dev/) through a managed local extension.-Pi is neither of Asymptote's two established integration shapes. It has no hooks configuration file to merge a managed hook block into, and no OpenTelemetry support to point at the local collector. Its documented observation surface is the TypeScript extension API, which makes the integration extension-shaped — one Asymptote-owned extension file that forwards runtime events to `beacon-hooks`, the same shape as the OpenCode and Cline plugins.--Install it with:+Pi fits neither of Asymptote's two usual integration shapes. It has no hooks configuration file to merge a managed hook block into, and no OpenTelemetry support to point at the local collector. Its documented observation surface is the TypeScript extension API, so the integration is extension-shaped: one Asymptote-owned extension file forwards runtime events to `beacon-hooks`, the same shape as the OpenCode and Cline plugins.```bashbeacon endpoint hooks install --harness pi@@ -17,8 +15,11 @@ beacon endpoint hooks install --harness pi## Prerequisites+Before enabling Pi telemetry, make sure:+- Pi is installed and available as the `pi` executable, or has a local state directory at `~/.pi/agent`.- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.+- Pi is restarted after install or removal so new sessions load the updated extension.## Collection path@@ -29,15 +30,15 @@ Asymptote's managed Pi extension is a single TypeScript file at one of two docum| User | `~/.pi/agent/extensions/beacon.ts` || Project | `./.pi/extensions/beacon.ts` |-The distinction matters beyond the path. A project-level extension is subject to Pi's project-trust prompt, so the user-level location is the one that works without further interaction — and it is the path `beacon endpoint discover` reports on, so a project-level extension is not reflected in discovery output.+User level is the default. A project-level extension is subject to Pi's project-trust prompt, and `beacon endpoint discover` reports on the user path only, so a project-level extension does not appear in discovery output.-Asymptote identifies its own extension file by the marker `beacon-managed-pi-extension:v1`. The version suffix is part of the contract with the extension source rather than decoration: it is what will let a repair recognize a stale file instead of leaving it in place. A `beacon.ts` without the marker belongs to somebody else, so install will not overwrite it and discovery does not report it as Asymptote telemetry.+Asymptote identifies its own extension file by the marker `beacon-managed-pi-extension:v1`. The version suffix is part of the contract with the extension source: it is what lets a repair recognize a stale file instead of leaving it in place. A `beacon.ts` without the marker belongs to somebody else, so install will not overwrite it and discovery does not report it as Asymptote telemetry.-The integration is extension-based. Pi has no OpenTelemetry export for Asymptote to configure, so there is no OTLP path for this runtime.+Pi has no OpenTelemetry export for Asymptote to configure, so there is no OTLP path for this runtime.## Discovery and status-Asymptote detects Pi through the `pi` executable, treating the `~/.pi/agent` state directory as an additional signal. Pi installed through npm, pnpm, or bun is frequently absent from the `PATH` the endpoint process inherited — a shell alias, a version manager, or a per-project install all hide it — while its state directory is still there. Treating that directory as evidence keeps discovery from reporting "not detected" for a runtime someone is actively using, the same fallback the OpenCode, Cursor, and Hermes probes make for the same reason.+Asymptote detects Pi through the `pi` executable, and treats the `~/.pi/agent` state directory as an additional signal. Pi installed through npm, pnpm, or bun is often missing from the `PATH` the endpoint process inherited, because a shell alias, a version manager, or a per-project install can all hide it while the state directory is still present. The OpenCode, Cursor, and Hermes probes use the same fallback.```bash title="Show Pi discovery state"beacon endpoint discover --all --json@@ -51,13 +52,11 @@ Pi reports as the `pi_cli` harness with capability `plugin`:| `disabled` | A `beacon.ts` exists but carries no Asymptote marker, so it is somebody else's extension sharing the filename || `enabled` | Asymptote's managed extension is in place |-An unmarked extension file reports `disabled` rather than `enabled` on purpose. Reporting it as enabled would show the runtime as covered while no events arrive.+An unmarked extension file reports `disabled` rather than `enabled`, because reporting it as enabled would show the runtime as covered while no events arrive.## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. The extension is-installed separately, because Pi loads it from the user's own profile rather than from a machine-wide-location:+`beacon endpoint install` prepares shared endpoint config and runtime log paths. The extension is installed separately, because Pi loads it from the user's own profile rather than from a machine-wide location:```bashbeacon endpoint hooks install --harness pi # user level (default)@@ -66,69 +65,48 @@ beacon endpoint hooks status --harness pibeacon endpoint hooks uninstall --harness pi```-Install writes one file and refuses to touch a `beacon.ts` it did not write, so an extension of your-own that happens to share the filename is left alone and the install fails loudly rather than-silently replacing it.+Install writes one file and refuses to touch a `beacon.ts` it did not write, so an extension of your own that happens to share the filename is left alone and the install fails loudly rather than replacing it.-`status` reports `installed=false` when the extension exists but points at a hook binary that is no-longer there — after a Beacon uninstall, a partly applied update, or a home directory restored onto a-different machine. In each of those cases Pi loads an extension that spawns nothing, and reporting-that as installed would claim telemetry nobody is collecting.+`status` reports `installed=false` when the extension exists but points at a hook binary that is no longer there, which happens after a Beacon uninstall, a partly applied update, or a home directory restored onto a different machine. In each case Pi loads an extension that spawns nothing.## Telemetry coverage| Area | Support ||------|---------|-| Runtime discovery | Supported — executable and `~/.pi/agent` detection, managed extension path, and telemetry status |-| Harness attribution | Supported — `pi`, `pi.dev`, `pi_cli`, `pi-cli`, `pi_agent`, `pi-agent`, and `pi agent` all normalize to `pi_cli` |+| Runtime discovery | Supported through executable and `~/.pi/agent` detection, managed extension path, and telemetry status |+| Harness attribution | Supported. `pi`, `pi.dev`, `pi_cli`, `pi-cli`, `pi_agent`, `pi-agent`, and `pi agent` all normalize to `pi_cli` || Extension install, status, uninstall, and repair | Supported |-| Session lifecycle | Supported — `session.started` and `session.ended`, carrying why the session started or stopped |-| Prompts | Supported — `prompt.submitted`, with whether the input was typed, delivered over RPC, or injected by another extension |-| Tool use | Supported — `tool.invoked` before execution, then `tool.completed` or `tool.failed` |-| Commands | Supported — `command.executed` for the agent's `bash` tool and for commands you run with Pi's `!` prefix, which are marked as operator-initiated |-| File activity | Supported — `file.read`, `file.created`, and `file.modified`, with the unified patch on an edit |-| Agent reasoning | Supported — `agent.reasoning` from an assistant message's thinking parts, in the OTel GenAI reasoning-part shape |-| Token usage and cost | Supported — `token.usage` normalized into `gen_ai.usage`, including cache and reasoning tokens and runtime-reported cost |-| Approval decisions | Not available — Pi exposes no operator approval decision to observe. See [Known gaps](#known-gaps) |+| Session lifecycle | Supported. `session.started` and `session.ended`, carrying why the session started or stopped |+| Prompts | Supported. `prompt.submitted`, with whether the input was typed, delivered over RPC, or injected by another extension |+| Tool use | Supported. `tool.invoked` before execution, then `tool.completed` or `tool.failed` |+| Commands | Supported. `command.executed` for the agent's `bash` tool and for commands you run with Pi's `!` prefix, which are marked as operator-initiated |+| File activity | Supported. `file.read`, `file.created`, and `file.modified`, with the unified patch on an edit |+| Agent reasoning | Supported. `agent.reasoning` from an assistant message's thinking parts, in the OTel GenAI reasoning-part shape |+| Token usage and cost | Supported. `token.usage` normalized into `gen_ai.usage`, including cache and reasoning tokens and runtime-reported cost |+| Approval decisions | Not available. Pi exposes no operator approval decision to observe. See [Known gaps](#known-gaps) || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; the Pi extension installs separately in the logged-in user's context |+| MDM deployment | Supported for the endpoint agent. The Pi extension installs separately in the logged-in user's context |-Pi's harness name is matched by equality against a closed set of spellings rather than by substring, because `pi` is two characters and appears inside names that belong to other runtimes — `copilot` contains it. A substring rule would attribute every GitHub Copilot and VS Code Copilot session to Pi.+Harness names are matched against a closed set of spellings rather than by substring, because `pi` is two characters and appears inside names belonging to other runtimes. `copilot` contains it, so a substring rule would attribute every GitHub Copilot and VS Code Copilot session to Pi.## Data handling-Pi content is handled the same way as every other runtime: prompts, tool arguments, commands, paths,-diffs, and reasoning text retained in local or customer-controlled logs, with local secret redaction-and per-string limits applied before writing, a hash and byte count on each content-bearing event,-and events over the 64 KiB limit dropping raw and retained content while preserving stable metadata-and setting `field_truncated`.+Pi content is handled like every other runtime. Prompts, tool arguments, commands, paths, diffs, and reasoning text are retained in local or customer-controlled logs, with local secret redaction and per-string limits applied before writing, and a hash and byte count on each content-bearing event. Events over the 64 KiB limit drop raw and retained content, preserve stable metadata, and set `field_truncated`.-The extension itself sends nothing over the network. It spawns the local `beacon-hooks` binary with a-fixed argv and writes the event to its stdin; a send that has not completed in two seconds is-abandoned so Beacon cannot stall Pi's agent loop, and a failure to spawn costs the event rather than-the run.+The extension itself sends nothing over the network. It spawns the local `beacon-hooks` binary with a fixed argv and writes the event to its stdin. A send that has not completed in two seconds is abandoned so Beacon cannot stall Pi's agent loop, and a failure to spawn costs the event rather than the run.## Known gaps-- **No approval telemetry.** Pi's `tool_call` event lets an extension block a call, but that is an- extension deciding rather than an operator being asked — Pi exposes no operator approval decision- through the extension API. Beacon records these as tool activity and writes no approval events for- Pi, rather than synthesizing an approval nobody granted. The same choice applies to Cline for the- same reason. Detections in `rules/approval-abuse/` therefore do not fire on Pi activity.-- **No enforcement.** Consistent with every other runtime, enforcement stays behind the optional,- off-by-default policy-provider seam (`BEACON_POLICY_PROVIDER`), which is not wired to Pi. Pi's- blocking `tool_call` handler would make it a viable target for that seam later.-- **Streaming events are not collected.** The extension subscribes to seven of Pi's event types and- ignores the rest, which are provider-request and TUI-rendering internals. Assistant output is- recorded once when a message finalizes rather than token by token, so Beacon stays out of the- streaming path.-- **Project-level installs need Pi's trust prompt.** A `.pi/extensions/beacon.ts` is subject to Pi's- project-trust prompt, so a user-level install is the one that works without further interaction.+- **No approval telemetry.** Pi's `tool_call` event lets an extension block a call, but that is an extension deciding rather than an operator being asked. Pi exposes no operator approval decision through the extension API, so Beacon records these as tool activity and writes no approval events for Pi. Cline works the same way for the same reason. Detections in `rules/approval-abuse/` do not fire on Pi activity.+- **No enforcement.** As with every other runtime, enforcement stays behind the optional, off-by-default policy provider seam (`BEACON_POLICY_PROVIDER`), which is not wired to Pi. Pi's blocking `tool_call` handler makes it a viable target for that seam later.+- **Streaming events are not collected.** The extension subscribes to seven of Pi's event types and ignores the rest, which are provider-request and TUI-rendering internals. Assistant output is recorded once when a message finalizes rather than token by token, so Beacon stays out of the streaming path.+- **Project-level installs need Pi's trust prompt.** A `.pi/extensions/beacon.ts` is subject to Pi's project-trust prompt, so a user-level install is the one that works without further interaction.## Deployment notes-The extension is loaded when Pi starts, so an install taken while Pi is running takes effect on its-next launch. Confirm discovery sees the runtime, then generate one Pi event and check the log:+The extension is loaded when Pi starts, so an install taken while Pi is running takes effect on the next launch.++Confirm discovery sees the runtime, then generate one Pi event and check the log:```bash/opt/beacon/bin/beacon endpoint discover --all --jsondiff --git a/docs/runtimes/qwen-code.mdx b/docs/runtimes/qwen-code.mdxindex d86180d7..bb8c2302 100644--- a/docs/runtimes/qwen-code.mdx+++ b/docs/runtimes/qwen-code.mdx@@ -3,51 +3,40 @@ title: "Qwen Code"description: "Asymptote support details for Qwen Code endpoint telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports Qwen Code through native hook payloads sent to `beacon-hooks`.-Qwen Code is a Gemini CLI fork, but it does not carry Gemini's OpenTelemetry export, so there is no-endpoint to point at the local collector and no OTLP path for this runtime. What it does expose is a-documented hook system, so the integration is hook-shaped: Asymptote merges a managed hook block into-Qwen's own `settings.json`, the same shape as the Claude Code and Factory Droid installers.--Install it with:+Qwen Code is a Gemini CLI fork, but it does not carry Gemini's OpenTelemetry export, so there is no OTLP path for this runtime. Hooks are the only collection path. Asymptote merges a managed hook block into Qwen's own `settings.json`, the same way the Claude Code and Factory Droid installers do.```bashbeacon endpoint hooks install --harness qwen```-`--harness qwen-code` is accepted as well. `qwen-cli` is not — the product is Qwen Code.+`--harness qwen-code` is also accepted. `qwen-cli` is not, because the product is Qwen Code.## Prerequisites+Before enabling Qwen Code telemetry, make sure:+- Qwen Code is installed and available as the `qwen` executable, or has a local config directory at `~/.qwen`.- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.+- On Windows, `bash` is on `PATH`. Asymptote's hooks declare `shell: bash`. See [Hook shell](#hook-shell).+- Project-level hooks are only used in a folder Qwen Code trusts. See [Known gaps](#known-gaps).- Qwen Code is restarted after hook install or removal so new sessions load the updated settings.-- On Windows, `bash` is on `PATH`. Asymptote's hooks declare `shell: bash`; see [Hook shell](#hook-shell).-- Project-level hooks are only executed in a folder Qwen Code trusts. See [Known gaps](#known-gaps).## Collection path-Qwen Code resolves settings from two locations, with project settings taking precedence over user-settings:+Qwen Code reads settings from two locations, with project settings taking precedence over user settings:| Level | Settings path ||-------|---------------|| User | `~/.qwen/settings.json` || Project | `./.qwen/settings.json` |-The user level is the default because a project-level install only takes effect once Qwen trusts the-folder. The user path is also the one `beacon endpoint discover` reports on, so a project-level-install is not reflected in discovery output.+User level is the default. A project-level install only takes effect once Qwen trusts the folder, and `beacon endpoint discover` reports on the user path only, so a project-level install does not appear in discovery output.-`settings.json` is shared with the user's own configuration — model, theme, MCP servers, their own-hooks — so install goes through a merge rather than a rewrite. Unrelated top-level keys are preserved-verbatim, non-Asymptote hooks in the same event group survive, and a re-install replaces Asymptote's-own entries instead of stacking a second copy beside them. Asymptote identifies its own entries by-the `--platform qwen` argument in the hook command, since it has no file of its own in `~/.qwen` to-stamp.+`settings.json` also holds the user's own configuration, such as model, theme, MCP servers, and their own hooks. Install merges into that file rather than rewriting it: unrelated top-level keys are preserved, non-Asymptote hooks in the same event group survive, and a re-install replaces Asymptote's entries instead of adding a second copy. Asymptote recognizes its own entries by the `--platform qwen` argument in the hook command.### Registered events@@ -55,62 +44,36 @@ Asymptote registers every Qwen event that carries endpoint signal:| Qwen event | Adapter subcommand | Matcher | Timeout ||------------|--------------------|---------|---------|-| `SessionStart` | `session-start` | — | Qwen default |-| `UserPromptSubmit` | `prompt-submit` | — | 30000 ms |+| `SessionStart` | `session-start` | n/a | Qwen default |+| `UserPromptSubmit` | `prompt-submit` | n/a | 30000 ms || `PreToolUse` | `pre-tool` | `*` | 10000 ms || `PostToolUse` | `post-tool` | `*` | 10000 ms || `PostToolUseFailure` | `post-tool` | `*` | 10000 ms || `PermissionRequest` | `permission-request` | `*` | 10000 ms |-| `Stop` | `stop` | — | 45000 ms |-| `SubagentStart` | `subagent-start` | — | Qwen default |-| `SubagentStop` | `subagent-stop` | — | Qwen default |-| `SessionEnd` | `session-end` | — | Qwen default |+| `Stop` | `stop` | n/a | 45000 ms |+| `SubagentStart` | `subagent-start` | n/a | Qwen default |+| `SubagentStop` | `subagent-stop` | n/a | Qwen default |+| `SessionEnd` | `session-end` | n/a | Qwen default |-`PostToolUseFailure` is registered alongside `PostToolUse` because a failed tool is a separate event-in Qwen and would otherwise be invisible. `PermissionRequest` is what makes an approval prompt-observable at all. Events with no timeout entry inherit Qwen's own default of 60000 ms, which is the-right answer for the ones that do no work beyond writing a line.+A failed tool is a separate event in Qwen, so `PostToolUseFailure` is registered alongside `PostToolUse`. `PermissionRequest` is what makes an approval prompt observable. Events with no timeout listed use Qwen's own default of 60000 ms.<Warning>-**Qwen hook timeouts are milliseconds, not seconds.** This is the one place Qwen's settings format-diverges from Claude Code's while looking identical, and it fails quietly in the direction that-hurts. Claude Code reads `timeout` as seconds, so a Claude-style `10` means 10 ms to Qwen — not-enough for a hook process to start, read stdin, resolve a git branch, and append to a JSONL file, so-every tool event would be killed mid-write. The install would report success and the settings file-would look right while the runtime log stayed empty or truncated. Asymptote writes millisecond values-for this runtime; keep the unit in mind if you hand-edit them.+**Qwen hook timeouts are milliseconds, not seconds.** Claude Code reads `timeout` as seconds, so a Claude-style `10` means 10 ms to Qwen. That is not enough time for a hook process to start, read stdin, and append to the log, so every tool event is killed mid-write while the install still reports success. Asymptote writes millisecond values for this runtime. Keep the unit in mind if you hand-edit them.</Warning>### Hook shell-Every hook Asymptote writes for Qwen carries `shell: bash`. Qwen runs hook commands through a shell-of its choosing and documents exactly two values a hook may ask for, `bash` and `powershell`. Unlike-Claude Code, which runs hook commands through Git Bash on Windows regardless, Qwen only uses bash-when the hook configuration asks for it.+Every hook Asymptote writes for Qwen carries `shell: bash`. Qwen accepts two values, `bash` and `powershell`, and only uses bash when the hook configuration asks for it. Claude Code, by contrast, runs hook commands through Git Bash on Windows regardless.-Asymptote builds its hook command with POSIX single-quoting, which is what a Windows path needs — in-double quotes, bash still expands `$` and eats a doubled backslash, so a profile directory containing-a `$` would vanish and a UNC path would lose a separator. Left unset on Windows, a Node-hosted-runtime lands on the platform default of `cmd.exe`, where those quotes are literal characters and-every hook fails to start while the install still reports success. That is the same silent-failure-shape as a seconds-valued timeout, so it gets the same care. On macOS and Linux, `bash` names the-shell that would have run anyway.+Asymptote quotes its hook command with POSIX single quotes, which is what a Windows path needs. If `shell` were left unset on Windows, a Node-hosted runtime would fall back to `cmd.exe`, where those quotes are literal characters and every hook fails to start while the install still reports success. On macOS and Linux, `bash` names the shell that would have run anyway.-### Events that are deliberately not collected+### Events that are not collected-Qwen offers several fire-and-forget events Asymptote does not register: `MessageDisplay`,-`StopFailure`, `PostCompact`, `SessionDelete`, and the todo pair. `MessageDisplay` alone fires roughly-every 200 ms for the length of every reply, and spawning a process that often to record assistant-text Asymptote does not otherwise retain would cost more than it tells anyone.+Asymptote does not register Qwen's fire-and-forget events: `MessageDisplay`, `StopFailure`, `PostCompact`, `SessionDelete`, and the todo pair. `MessageDisplay` alone fires roughly every 200 ms for the length of every reply, and it carries assistant text that Asymptote does not otherwise retain.## Discovery and status-Asymptote detects Qwen Code through the `qwen` executable, treating the `~/.qwen` config directory as-an additional signal. Qwen Code installs through npm, and a version manager, a shell alias, or a-per-project install all hide the binary from the `PATH` the endpoint process inherited while-`~/.qwen` is still there. Treating that directory as evidence keeps discovery from reporting "not-detected" for a runtime someone is actively using — the same fallback the OpenCode, Cursor, Pi, and-Hermes probes make for the same reason.+Asymptote detects Qwen Code through the `qwen` executable, and treats the `~/.qwen` config directory as an additional signal. Qwen Code installs through npm, so a version manager, a shell alias, or a per-project install can hide the binary from the endpoint process's `PATH` while `~/.qwen` is still present. The OpenCode, Cursor, Pi, and Hermes probes use the same fallback.```bash title="Show Qwen Code discovery state"beacon endpoint discover --all --json@@ -125,13 +88,9 @@ Qwen Code reports as the `qwen_code` harness with capability `hooks`:| `disabled` | Hooks are turned off by `disableAllHooks`, or the file exists with no Asymptote `--platform qwen` entry || `enabled` | Asymptote's Qwen Code hooks are configured |-Two of these are worth spelling out. A settings file carrying hooks that are not Asymptote's reports-`disabled`, not `enabled`, because reporting it as enabled would claim telemetry Asymptote is not-collecting. Invalid JSON reports `misconfigured` rather than `missing`, because install will refuse to-write to that file and "not found" would send you looking for a file that is right there.+A settings file with hooks that are not Asymptote's reports `disabled` rather than `enabled`, because Asymptote is not collecting from them. Invalid JSON reports `misconfigured` rather than `missing`, because the file is there and install will refuse to write to it.-`disableAllHooks` is Qwen's own kill switch. Asymptote's hooks can be present in the file and still-never run, and that is fixed in Qwen's settings rather than by re-running the installer.+`disableAllHooks` is Qwen's own kill switch. Asymptote's hooks can be present in the file and still never run. Fix that in Qwen's settings, not by re-running the installer.```bash title="Show Qwen Code hook status"beacon endpoint hooks status --harness qwen@@ -139,9 +98,7 @@ beacon endpoint hooks status --harness qwen## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Qwen Code hooks are-installed separately, because Qwen loads them from the user's own profile rather than from a-machine-wide location:+`beacon endpoint install` prepares shared endpoint config and runtime log paths. Qwen Code hooks are installed separately, because Qwen loads them from the user's own profile rather than from a machine-wide location:```bashbeacon endpoint hooks install --harness qwen # user level (default)@@ -150,145 +107,78 @@ beacon endpoint hooks status --harness qwenbeacon endpoint hooks uninstall --harness qwen```-A project-level install reports that Qwen Code runs project hooks only in a trusted folder, because-an install that reported plain success into an untrusted folder would be reporting something untrue:-the file is written, and nothing runs.+A project-level install reports that Qwen Code runs project hooks only in a trusted folder. Without that, the file is written and nothing runs.-`beacon endpoint install` does not configure Qwen Code. Passing `--harness qwen` to it fails with a-message pointing at `beacon endpoint hooks install`, rather than silently doing nothing.+`beacon endpoint install` does not configure Qwen Code. Passing `--harness qwen` to it fails with a message pointing at `beacon endpoint hooks install`.## Telemetry coverage| Area | Support ||------|---------|-| Runtime discovery | Supported — executable and `~/.qwen` detection, settings path, and telemetry status |-| Harness attribution | Supported — `qwen`, `qwen_code`, `qwen-code`, `qwen code`, `qwencode`, `qwen_cli`, `qwen-cli`, `qwen cli`, `qwen_coder`, `qwen-coder`, and `qwen coder` all normalize to `qwen_code` |+| Runtime discovery | Supported through executable and `~/.qwen` detection, settings path, and telemetry status |+| Harness attribution | Supported. `qwen`, `qwen_code`, `qwen-code`, `qwen code`, `qwencode`, `qwen_cli`, `qwen-cli`, `qwen cli`, `qwen_coder`, `qwen-coder`, and `qwen coder` all normalize to `qwen_code` || Hook install, status, uninstall, and repair | Supported |-| Session lifecycle | Supported — `SessionStart` and `SessionEnd`, with the start `source` preserved |-| Prompts | Supported — `prompt.submitted` from `UserPromptSubmit` |-| Tool use | Supported — pre-tool and post-tool activity, with `tool.failed` for `PostToolUseFailure` |-| Commands | Supported — `command.executed` for `run_shell_command` |-| File activity | Supported — `file.read`, `file.modified`, and file paths with an operation, including diffs on an edit |-| Subagents | Supported — `SubagentStart` and `SubagentStop` |-| Approval decisions | Supported — observed from `PermissionRequest`, not synthesized from pre-tool |-| Tool call identity | Supported — Qwen's own `tool_use_id` / `tool_call_id` is promoted to `gen_ai.tool.call.id` as the join key between pre-tool and post-tool events |-| Token usage and cost | Not normalized — see [Known gaps](#known-gaps) |+| Session lifecycle | Supported through `SessionStart` and `SessionEnd`, with the start `source` preserved |+| Prompts | Supported. `prompt.submitted` from `UserPromptSubmit` |+| Tool use | Supported for pre-tool and post-tool activity, with `tool.failed` for `PostToolUseFailure` |+| Commands | Supported. `command.executed` for `run_shell_command` |+| File activity | Supported. `file.read`, `file.modified`, and file paths with an operation, including diffs on an edit |+| Subagents | Supported through `SubagentStart` and `SubagentStop` |+| Approval decisions | Supported. Observed from `PermissionRequest`, not synthesized from pre-tool |+| Tool call identity | Supported. Qwen's `tool_use_id` / `tool_call_id` is promoted to `gen_ai.tool.call.id` and joins pre-tool and post-tool events |+| Token usage and cost | Not normalized. See [Known gaps](#known-gaps) || Local JSONL and dashboard | Supported |-| MDM deployment | Supported for the endpoint agent; Qwen hooks are installed separately in the logged-in user's context or project context |+| MDM deployment | Supported for the endpoint agent. Qwen hooks are installed separately in the logged-in user's context or project context |-Qwen Code's harness name is matched by equality against a closed set of spellings rather than by-substring, and the reason is specific to this runtime: every Qwen model id begins with the same four-letters the harness does — `qwen3-coder-plus`, `qwen-max`, `qwen-turbo`. A substring rule would report-any event whose harness attribute happened to carry a model string as a Qwen Code session, which is-how a model name ends up masquerading as a runtime in a dashboard grouped by `harness.name`.+Harness names are matched against a closed set of spellings rather than by substring, because every Qwen model id starts with the same four letters as the harness: `qwen3-coder-plus`, `qwen-max`, `qwen-turbo`. A substring rule would report any event carrying a Qwen model string as a Qwen Code session.-Both `qwen` and `qwen_code` arrive in practice — the hook path installs with `--platform qwen`, while-an OTLP resource attribute carries whatever the runtime calls itself — and pinning both is what keeps-one session from being recorded under two names.+Both `qwen` and `qwen_code` arrive in practice. The hook path installs with `--platform qwen`, while an OTLP resource attribute carries whatever the runtime calls itself. Pinning both keeps one session from being recorded under two names.### Tool taxonomy-Qwen sends the Claude Code payload *shape* but not Claude's tool *names*: its built-ins are-snake_case ids inherited from the Gemini CLI it forked. Asymptote classifies them against a closed-set, matched by equality:+Qwen sends the Claude Code payload shape but not Claude's tool names. Its built-ins are snake_case ids inherited from the Gemini CLI it forked, and Asymptote matches them against a closed set:| Qwen built-in | Action | `file.operation` ||---------------|--------|------------------|-| `run_shell_command` | `command.executed` | — |+| `run_shell_command` | `command.executed` | n/a || `read_file`, `read_many_files`, `list_directory`, `glob`, `grep_search`, `search_file_content` | `file.read` | `read` || `write_file` | `file.modified` | `create` || `edit`, `replace`, `notebook_edit` | `file.modified` | `modify` |-Without this mapping, the generic substring classifier is wrong in both directions that matter:-`write_file`, `edit`, `replace`, and `notebook_edit` would fall through to `tool.invoked` because the-default only recognizes Claude's `Write`/`Edit`/`MultiEdit`, and `list_directory`, `glob`, and-`grep_search` would not be recorded as reads. Both are misclassification rather than absence, which is-the worse failure: the event is there, the action is wrong, and nothing looks broken.--`read_many_files`, `search_file_content`, and `replace` are the Gemini CLI spellings that Qwen Code-renamed. They are kept because a hook installed against one version can receive payloads from another-after an upgrade; an id that no longer exists costs one dead map entry, while a missing one costs a-misclassified event.--The set is closed rather than substring-matched so that an MCP tool whose name happens to contain-`edit` or `glob` is not classified as a Qwen built-in — MCP tools are named by whoever wrote the-server. Qwen's non-filesystem built-ins (`web_fetch`, `web_search`, `todo_write`, `save_memory`,-`task`, `skill`) stay on the shared path, where the MCP rule and the `tool.invoked` fallback already-give the right answer.--A tool that failed is classified as a failure before its name is consulted, so a `write_file` that hit-`EACCES` is recorded as `tool.failed` rather than as a successful `file.modified`, and it is not sent-down the diff path. Asymptote reads three independent failure signals, because any of them can arrive-alone: the `PostToolUseFailure` event name, a non-empty `error`, and Qwen's `is_interrupt` flag for an-interrupt reported with an empty message.+Without this mapping the generic classifier is wrong in both directions. `write_file`, `edit`, `replace`, and `notebook_edit` fall through to `tool.invoked` because the default only recognizes Claude's `Write`, `Edit`, and `MultiEdit`, and `list_directory`, `glob`, and `grep_search` are not recorded as reads. Both are misclassifications rather than gaps: the event is present, the action is wrong, and nothing looks broken.++`read_many_files`, `search_file_content`, and `replace` are Gemini CLI spellings that Qwen Code renamed. They are kept because a hook installed against one version can receive payloads from another after an upgrade.++The set is closed rather than substring-matched so an MCP tool whose name contains `edit` or `glob` is not classified as a Qwen built-in. Qwen's non-filesystem built-ins (`web_fetch`, `web_search`, `todo_write`, `save_memory`, `task`, `skill`) stay on the shared path, where the MCP rule and the `tool.invoked` fallback already give the right answer.++A failed tool is classified as a failure before its name is consulted, so a `write_file` that hit `EACCES` is recorded as `tool.failed` rather than a successful `file.modified`, and it does not go down the diff path. Asymptote reads three independent failure signals, since any of them can arrive alone: the `PostToolUseFailure` event name, a non-empty `error`, and Qwen's `is_interrupt` flag.## Approvals and enforcement-Approval telemetry comes from Qwen's `PermissionRequest` event and is recorded as observed — an-operator was actually asked. Asymptote does not synthesize an approval from a pre-tool notification-for this runtime.+Approval telemetry comes from Qwen's `PermissionRequest` event and is recorded as observed, because an operator was actually asked. Asymptote does not synthesize an approval from a pre-tool notification for this runtime.-Asymptote's `PreToolUse` hook answers with an empty object, which is a security property rather than-a convention. Qwen's `PreToolUse` contract reads a decision from-`hookSpecificOutput.permissionDecision`, where `allow` means *run the tool without the usual approval-prompt*. An observing hook that answered `allow` would therefore not be observing — it would silently-disarm the user's own permission prompts for every tool call, on a runtime where the hook was-installed to watch. An empty object carries no decision, so Qwen's normal permission flow runs-untouched.+Asymptote's `PreToolUse` hook answers with an empty object. Qwen's `PreToolUse` contract reads a decision from `hookSpecificOutput.permissionDecision`, where `allow` means run the tool without the usual approval prompt. A hook that answered `allow` would disarm the user's own permission prompts for every tool call. An empty object carries no decision, so Qwen's normal permission flow runs untouched.-Enforcement stays behind the optional, off-by-default policy-provider seam-(`BEACON_POLICY_PROVIDER`), which is inert unless it names an executable and fails open on any error.-When a provider denies a call, Qwen shares Claude Code's deny shape exactly:-`hookSpecificOutput.permissionDecision` with a `permissionDecisionReason`.+Enforcement stays behind the optional, off-by-default policy provider seam (`BEACON_POLICY_PROVIDER`), which is inert unless it names an executable and fails open on any error. When a provider denies a call, Qwen uses Claude Code's deny shape: `hookSpecificOutput.permissionDecision` with a `permissionDecisionReason`.## Data handling-Qwen Code content is handled the same way as every other runtime: prompts, tool arguments, commands,-paths, and diffs retained in local or customer-controlled logs, with local secret redaction and-per-string limits applied before writing, a hash and byte count on each content-bearing event, and-events over the 64 KiB limit dropping raw and retained content while preserving stable metadata and-setting `field_truncated`.+Qwen Code content is handled like every other runtime. Prompts, tool arguments, commands, paths, and diffs are retained in local or customer-controlled logs, with local secret redaction and per-string limits applied before writing, and a hash and byte count on each content-bearing event. Events over the 64 KiB limit drop raw and retained content, preserve stable metadata, and set `field_truncated`.-Qwen carries real signal with no endpoint-schema field of its own — `permission_mode` on every tool-event, `source` on `SessionStart`, `stop_hook_active` and the `context_usage` / `context_limit` /-`input_tokens` trio on `Stop`. The verbatim payload is preserved under `raw.qwen` rather than-inventing schema fields for one runtime. It travels the whole event's own path through sanitization,-so `raw` is secret-redacted and string-limited like every other field, and it is the first thing-dropped when an event exceeds the size ceiling.+Qwen carries signal with no endpoint-schema field of its own: `permission_mode` on every tool event, `source` on `SessionStart`, and `stop_hook_active` plus the `context_usage` / `context_limit` / `input_tokens` trio on `Stop`. Asymptote preserves the verbatim payload under `raw.qwen` rather than inventing schema fields for one runtime. It travels the event's normal path through sanitization, so `raw` is secret-redacted and string-limited like every other field, and it is the first thing dropped when an event exceeds the size ceiling.## Known gaps-- **No OTLP path.** Qwen Code is a Gemini CLI fork without Gemini's OpenTelemetry export, so there is- no collector endpoint to configure. Hooks are the only collection path for this runtime, and- `beacon endpoint install --harness qwen` says so rather than appearing to succeed.-- **Token usage is not normalized.** Qwen's `Stop` payload carries `context_usage`, `context_limit`,- and `input_tokens`, which are session-level context counters rather than per-call usage. They are- preserved under `raw.qwen` but are not normalized into `gen_ai.usage`, so Qwen Code activity does- not appear in `beacon token-usage` reports or the dashboard token view. Cline, OpenCode, and Pi- report usage their runtimes expose per message.-- **A policy deny is honored in one of two phases.** The seam runs in both the `pre-tool` and- `permission-request` hooks, and Asymptote returns Claude Code's deny shape, which Qwen's- `PreToolUse` contract honors. Qwen's `PermissionRequest` event reads a differently shaped- `hookSpecificOutput.decision` object, so a deny raised from that phase is not honored there. Because- the seam fails open, the cost is a deny that does not take effect on one phase, never a tool call- blocked for the wrong reason.-- **Assistant text is not collected.** `MessageDisplay` is deliberately not registered, so Asymptote- records no assistant output or reasoning for Qwen Code. See- [Events that are deliberately not collected](#events-that-are-deliberately-not-collected).-- **Project-level installs need a trusted folder.** Qwen gates project hooks behind trusted-folder- status, so a user-level install is the one that works without further interaction. Grok Build- carries the same caveat for the same reason.-- **Payload fixtures are built from documentation.** Asymptote's Qwen fixtures are constructed from- Qwen Code's published hooks documentation rather than captured from a running install. The- documentation specifies the envelope and per-event fields precisely, so the shapes are the- documented contract — but they are not evidence that a shipped build sends exactly this. Qwen- documents its hook input as a forward-extensible contract, so the mapper reads the fields it needs- and ignores the rest.+- **No OTLP path.** Qwen Code is a Gemini CLI fork without Gemini's OpenTelemetry export, so there is no collector endpoint to configure. Hooks are the only collection path, and `beacon endpoint install --harness qwen` says so rather than appearing to succeed.+- **Token usage is not normalized.** Qwen's `Stop` payload carries `context_usage`, `context_limit`, and `input_tokens`, which are session-level context counters rather than per-call usage. They are preserved under `raw.qwen` but not normalized into `gen_ai.usage`, so Qwen Code activity does not appear in `beacon token-usage` reports or the dashboard token view.+- **A policy deny is honored in one of two phases.** The seam runs in both the `pre-tool` and `permission-request` hooks, and Asymptote returns Claude Code's deny shape, which Qwen's `PreToolUse` contract honors. Qwen's `PermissionRequest` event reads a differently shaped `hookSpecificOutput.decision` object, so a deny raised from that phase is not honored. Because the seam fails open, the cost is a deny that does not take effect on one phase, never a tool call blocked for the wrong reason.+- **Assistant text is not collected.** `MessageDisplay` is not registered, so Asymptote records no assistant output or reasoning for Qwen Code. See [Events that are not collected](#events-that-are-not-collected).+- **Project-level installs need a trusted folder.** Qwen gates project hooks behind trusted-folder status, so a user-level install is the one that works without further interaction. Grok Build has the same caveat.+- **Payload fixtures are built from documentation.** Asymptote's Qwen fixtures are constructed from Qwen Code's published hooks documentation rather than captured from a running install. The documentation specifies the envelope and per-event fields precisely, so the shapes match the documented contract, but they are not evidence that a shipped build sends exactly this.## Deployment notes-Settings are read when Qwen Code starts, so an install taken while Qwen is running takes effect on its-next launch. Restart Qwen after installing or removing hooks.+Settings are read when Qwen Code starts, so an install taken while Qwen is running takes effect on the next launch. Restart Qwen after installing or removing hooks.Confirm discovery sees the runtime, then generate one Qwen Code event and check the log:@@ -299,10 +189,14 @@ Confirm discovery sees the runtime, then generate one Qwen Code event and checkgrep '"name":"qwen_code"' ~/.beacon/endpoint/logs/runtime.jsonl | tail -3```-If Qwen telemetry is missing, check the selected level, confirm `settings.json` contains commands with-`--platform qwen`, confirm `disableAllHooks` is not set, confirm hook timeouts are millisecond values,-trust the folder for a project-level install, and restart Qwen so new sessions pick up the updated-settings.+If Qwen telemetry is missing:++- Check the selected level, user or project.+- Confirm `settings.json` contains commands with `--platform qwen`.+- Confirm `disableAllHooks` is not set.+- Confirm hook timeouts are millisecond values.+- Trust the folder for a project-level install.+- Restart Qwen so new sessions pick up the updated settings.## Relateddiff --git a/docs/runtimes/vscode.mdx b/docs/runtimes/vscode.mdxindex e317e9ea..30375a21 100644--- a/docs/runtimes/vscode.mdx+++ b/docs/runtimes/vscode.mdx@@ -3,7 +3,7 @@ title: "VS Code"description: "Asymptote support details for VS Code Copilot and hook telemetry"----## Runtime Overview+## Runtime overviewAsymptote supports VS Code primarily through GitHub Copilot Chat OpenTelemetry export to Asymptote's localhost collector. VS Code hooks are also supported as an optional preview path when your organization allows them.diff --git a/docs/sdk/index.mdx b/docs/sdk/index.mdxindex d3d5f0b8..47c8f1e9 100644--- a/docs/sdk/index.mdx+++ b/docs/sdk/index.mdx@@ -3,7 +3,7 @@ title: "Asymptote Observe SDK"description: "Instrument cloud-hosted agent applications with Beacon-compatible telemetry"----## SDK Overview+## SDK overviewAsymptote Observe instruments cloud-hosted agent applications and exports OpenTelemetry traces that remain compatible with Beacon's normalized endpoint event model. Use it for servers, serverless functions, workers, and hosted agent platforms where installing the local Beacon endpoint agent is not the right fit.@@ -11,7 +11,7 @@ Hosted Observe ingest is available through Asymptote Managed. To get an `ASYMPTOThe open-source `agent-beacon` repository currently includes the TypeScript package `@asymptote/sdk`. It provides the `Observe` module for OpenTelemetry setup, common AI SDK instrumentation, manual span wrappers, lifecycle helpers, and Beacon compatibility attributes.-## What Asymptote Captures+## What Asymptote capturesAsymptote Observe is OpenTelemetry-first. It records supported model calls, agent turns, tool calls, custom orchestration steps, errors, and Beacon compatibility attributes as spans that can be sent to Asymptote Managed hosted Observe or a customer-managed OTLP collector.@@ -46,7 +46,7 @@ Supported cloud SDK paths:</Card></Columns>-## Choose The Right Surface+## Choose the right surfaceUse the SDK when agent activity runs in application code you control. Use Asymptote endpoint or CI collection when activity happens in a local harness or ephemeral build job.@@ -57,7 +57,7 @@ Use the SDK when agent activity runs in application code you control. Use Asympt| Local coding and knowledge-worker harnesses | [Asymptote endpoint agent](/runtimes) || CI jobs running Claude Code | [`beacon ci`](/cli/ci) |-## SDK And Endpoint Telemetry+## SDK and endpoint telemetryThe SDK and Asymptote endpoint telemetry share an event contract, but they target different deployment surfaces.diff --git a/docs/sdk/instrumentation.mdx b/docs/sdk/instrumentation.mdxindex bf83b38f..7ed0575d 100644--- a/docs/sdk/instrumentation.mdx+++ b/docs/sdk/instrumentation.mdx@@ -3,7 +3,7 @@ title: "Instrumentation"description: "Initialize Asymptote Observe and configure TypeScript SDK instrumentation"----## Instrumentation Model+## Instrumentation modelUse `Observe.initialize()` once at application startup to configure the OpenTelemetry provider, exporter, resource attributes, and supported AI SDK instrumentations.@@ -19,7 +19,7 @@ Observe.initialize({By default, the SDK creates OpenAI and Anthropic OpenLLMetry instrumentations when they are not disabled.-## Initialize Options+## Initialize options| Option | Purpose || --- | --- |@@ -41,7 +41,7 @@ By default, the SDK creates OpenAI and Anthropic OpenLLMetry instrumentations wh`Observe.initialize()` may only be called once per process configuration. Call `Observe.shutdown()` before reinitializing with different options. A later `Observe.initialize({ instrumentModules })` call can patch additional modules without replacing the provider.-## Instrument Modules+## Instrument modulesPass modules to `instrumentModules` when they may be loaded before auto-instrumentation runs.@@ -67,7 +67,7 @@ Supported module keys in the current TypeScript SDK:| `Anthropic` or `anthropic` | `@anthropic-ai/sdk` || `claudeAgentSDK` or `claudeAgentSdk` | `@anthropic-ai/claude-agent-sdk` query export |-## Patch Modules After Initialization+## Patch modules after initializationUse `Observe.patch()` when the SDK has already initialized and a module needs to be instrumented later, such as inside a framework-specific module boundary.@@ -86,7 +86,7 @@ Observe.patch({`Observe.patch()` requires at least one module. It applies supported OpenLLMetry instrumentation and wraps Claude Agent SDK query functions when the module object is writable.-## Existing OpenTelemetry Providers+## Existing OpenTelemetry providersIf your application already owns OpenTelemetry setup, use `Observe.instrumentations()` with your provider instead of calling `Observe.initialize()` twice.diff --git a/docs/sdk/integrations-anthropic.mdx b/docs/sdk/integrations-anthropic.mdxindex 551533c0..6e18e6eb 100644--- a/docs/sdk/integrations-anthropic.mdx+++ b/docs/sdk/integrations-anthropic.mdx@@ -3,7 +3,7 @@ title: "Anthropic"description: "Instrument Anthropic SDK calls with Asymptote Observe"----## Integration Overview+## Integration overviewUse this integration when your application calls Anthropic's `@anthropic-ai/sdk` TypeScript package directly. Asymptote Observe uses OpenLLMetry's Anthropic instrumentation so Anthropic model calls flow through the same exporter and Beacon-compatible attribute path as the rest of your agent telemetry.@@ -13,7 +13,7 @@ Initialize Asymptote Observe before creating the Anthropic client when possible.Using Claude Agent SDK instead of the direct provider SDK? See [Claude Agent SDK](/sdk/integrations-claude-agent-sdk).-## What Asymptote Captures+## What Asymptote captures- Anthropic model calls emitted by the OpenLLMetry Anthropic instrumentation.- OpenTelemetry resource attributes such as service name, SDK version, `beacon.origin=cloud`, and export mode.@@ -38,7 +38,7 @@ export ASYMPTOTE_API_KEY=...export ANTHROPIC_API_KEY=...```-## Getting Started+## Getting startedInitialize `Observe` before creating the Anthropic client when possible.@@ -75,7 +75,7 @@ await Observe.flush();All supported Anthropic SDK calls are now traced through the configured Asymptote exporter.-## Already-Loaded Clients+## Already-loaded clientsIf your application imports or creates the Anthropic client before initialization, pass the module to `instrumentModules` or patch it after initialization.@@ -95,7 +95,7 @@ Observe.initialize({});```-## Existing OpenTelemetry Providers+## Existing OpenTelemetry providersIf your application already owns OpenTelemetry setup, register only Asymptote's Anthropic instrumentation with your existing provider.@@ -120,7 +120,7 @@ registerInstrumentations({- If the Anthropic module is imported before initialization, pass it through `instrumentModules` or `Observe.patch()`.- Call `Observe.flush()` before short-lived scripts or jobs exit.-## What's Next+## What's next<Columns cols={2}><Card title="Claude Agent SDK" icon="robot" href="/sdk/integrations-claude-agent-sdk">diff --git a/docs/sdk/integrations-claude-agent-sdk.mdx b/docs/sdk/integrations-claude-agent-sdk.mdxindex 2bd74102..dbf5a36a 100644--- a/docs/sdk/integrations-claude-agent-sdk.mdx+++ b/docs/sdk/integrations-claude-agent-sdk.mdx@@ -3,7 +3,7 @@ title: "Claude Agent SDK"description: "Wrap Claude Agent SDK query functions with Asymptote Observe"----## Integration Overview+## Integration overviewUse this integration when your application runs Claude Agent SDK queries through `@anthropic-ai/claude-agent-sdk`. Asymptote Observe can wrap the query function to create a Beacon-compatible root span for each agent turn.@@ -13,7 +13,7 @@ Claude Agent SDK integration is currently a query wrapper, not a custom hook adaFor direct Anthropic API calls through `@anthropic-ai/sdk`, use [Anthropic](/sdk/integrations-anthropic).-## What Asymptote Captures+## What Asymptote captures- A `claude_agent_sdk.query` span for wrapped query calls.- `beacon.harness.name=claude_agent_sdk`.@@ -38,7 +38,7 @@ Set environment variables:export ASYMPTOTE_API_KEY=...```-## Getting Started+## Getting startedWrap the query function before using it.@@ -63,7 +63,7 @@ for await (const message of stream) {await Observe.flush();```-## Prompt Detection+## Prompt detection`wrapClaudeAgentQuery()` records the first string argument as `beacon.prompt.text`. If the first argument is an object, it checks common prompt fields such as `prompt`, `input`, and `query`.@@ -75,7 +75,7 @@ await query({});```-## Patch Module Exports+## Patch module exportsIf you prefer patching the module object, pass it through `instrumentModules` during initialization.@@ -93,7 +93,7 @@ Observe.initialize({If ESM namespace exports are read-only, wrap the query function explicitly with `Observe.wrapClaudeAgentQuery()`.-## Group Agent Work+## Group agent workUse `Observe.observe()` around your entrypoint when one request combines Claude Agent SDK queries with other application work.@@ -121,7 +121,7 @@ const runInvestigation = Observe.observe(- If module patching does not work in an ESM namespace, use `Observe.wrapClaudeAgentQuery()` explicitly.- Call `Observe.flush()` before short-lived scripts or jobs exit.-## What's Next+## What's next<Columns cols={2}><Card title="Anthropic" icon="robot" href="/sdk/integrations-anthropic">diff --git a/docs/sdk/integrations-custom-agent-steps.mdx b/docs/sdk/integrations-custom-agent-steps.mdxindex 4c9a893d..275ceae2 100644--- a/docs/sdk/integrations-custom-agent-steps.mdx+++ b/docs/sdk/integrations-custom-agent-steps.mdx@@ -3,7 +3,7 @@ title: "Custom Agent Steps"description: "Trace custom agent orchestration with Observe.observe"----## Custom Step Tracking+## Custom step trackingUse `Observe.observe()` for orchestration steps, tool execution, policy checks, and handoffs that provider SDKs do not expose.@@ -11,7 +11,7 @@ Use `Observe.observe()` for orchestration steps, tool execution, policy checks,Custom agent steps are the fallback integration path for frameworks, internal tools, and orchestration code without a dedicated adapter. Wrap the function you control and add Beacon compatibility attributes that describe what happened.-## What Asymptote Captures+## What Asymptote captures- A span for each wrapped function call.- Input count and output type unless disabled.@@ -35,7 +35,7 @@ Set an export destination:export ASYMPTOTE_API_KEY=...```-## Getting Started+## Getting started```typescript title="Wrap a custom tool step" linesimport {@@ -68,7 +68,7 @@ await Observe.flush();The wrapped function preserves the original return behavior for sync functions, promises, and async iterables. Errors are recorded on the span and then rethrown.-## Avoid Sensitive Metadata+## Avoid sensitive metadataSet `ignoreInput` or `ignoreOutput` when wrapper metadata should avoid recording argument counts or output type.@@ -86,7 +86,7 @@ const redactSensitiveStep = Observe.observe();```-## Common Beacon Actions+## Common Beacon actionsUse Beacon compatibility attributes when a custom step should normalize into a known event category.@@ -132,7 +132,7 @@ See the [SDK reference](/sdk/reference#beacon-compatibility-attributes) for the- Use `ignoreInput` or `ignoreOutput` for sensitive steps.- Call `Observe.flush()` before short-lived scripts or jobs exit.-## What's Next+## What's next<Columns cols={2}><Card title="Observe" icon="diagram-project" href="/sdk/observe">diff --git a/docs/sdk/integrations-nextjs-serverless.mdx b/docs/sdk/integrations-nextjs-serverless.mdxindex bac089fa..1429c4d1 100644--- a/docs/sdk/integrations-nextjs-serverless.mdx+++ b/docs/sdk/integrations-nextjs-serverless.mdx@@ -3,7 +3,7 @@ title: "Next.js And Serverless"description: "Initialize Asymptote Observe in Next.js and short-lived serverless runtimes"----## Serverless Setup+## Serverless setupInitialize `Observe` once in the earliest Node-only entrypoint. In Next.js, use `instrumentation.ts` and guard against the edge runtime:@@ -19,7 +19,7 @@ Initialize `Observe` once in the earliest Node-only entrypoint. In Next.js, usenpm install @asymptote/sdk ai @ai-sdk/openai```-## Next.js Instrumentation+## Next.js instrumentation```typescript title="Initialize in instrumentation.ts" linesexport async function register() {@@ -35,7 +35,7 @@ export async function register() {This keeps SDK initialization out of edge runtimes while ensuring Node.js routes, server actions, and background work share the same tracing setup.-## Serverless Handlers+## Serverless handlersFor short-lived serverless invocations, call `Observe.flush()` before returning if traces are created immediately before the process may terminate.@@ -63,7 +63,7 @@ export async function POST(request: Request) {If the runtime owns a long-lived process, reserve `Observe.shutdown()` for graceful process shutdown rather than calling it after every request.-## Customer-Managed OTLP+## Customer-managed OTLPServerless and preview environments can send to a customer-managed collector by setting `OTEL_EXPORTER_OTLP_ENDPOINT` instead of Asymptote Managed hosted Observe credentials.diff --git a/docs/sdk/integrations-openai.mdx b/docs/sdk/integrations-openai.mdxindex 56cedd76..d9415016 100644--- a/docs/sdk/integrations-openai.mdx+++ b/docs/sdk/integrations-openai.mdx@@ -3,7 +3,7 @@ title: "OpenAI"description: "Instrument OpenAI SDK calls with Asymptote Observe"----## Integration Overview+## Integration overviewUse this integration when your application calls the `openai` JavaScript package directly. Asymptote Observe uses OpenLLMetry's OpenAI instrumentation so OpenAI spans flow through the same exporter and Beacon-compatible attribute path as the rest of your agent telemetry.@@ -11,7 +11,7 @@ Use this integration when your application calls the `openai` JavaScript packageInitialize Asymptote Observe before creating the OpenAI client when possible. The instrumentation captures supported OpenAI SDK spans without changing the way you call `openai`.-## What Asymptote Captures+## What Asymptote captures- OpenAI model calls emitted by the OpenLLMetry OpenAI instrumentation.- OpenTelemetry resource attributes such as service name, SDK version, `beacon.origin=cloud`, and export mode.@@ -36,7 +36,7 @@ export ASYMPTOTE_API_KEY=...export OPENAI_API_KEY=...```-## Getting Started+## Getting startedInitialize `Observe` before creating the OpenAI client when possible.@@ -67,7 +67,7 @@ await Observe.flush();All supported OpenAI SDK calls are now traced through the configured Asymptote exporter.-## Already-Loaded Clients+## Already-loaded clientsIf your application imports or creates the OpenAI client before initialization, pass the module to `instrumentModules` or patch it after initialization.@@ -99,7 +99,7 @@ const response = await openai.chat.completions.create({await Observe.flush();```-## Group Calls With Custom Spans+## Group calls with custom spansWrap application logic with `Observe.observe()` when one route, job, or agent turn makes multiple OpenAI calls and you want them grouped under one parent span.@@ -129,7 +129,7 @@ const reviewPullRequest = Observe.observe();```-## Existing OpenTelemetry Providers+## Existing OpenTelemetry providersIf your application already owns OpenTelemetry setup, register Asymptote's OpenAI instrumentation with your existing provider instead of calling `Observe.initialize()` twice.@@ -154,7 +154,7 @@ registerInstrumentations({- If the OpenAI module is imported before initialization, pass it through `instrumentModules` or `Observe.patch()`.- Call `Observe.flush()` before short-lived scripts or jobs exit.-## What's Next+## What's next<Columns cols={2}><Card title="Instrumentation" icon="wand-magic-sparkles" href="/sdk/instrumentation">diff --git a/docs/sdk/integrations-vercel-ai-sdk.mdx b/docs/sdk/integrations-vercel-ai-sdk.mdxindex e9342e1a..cdf6a3e5 100644--- a/docs/sdk/integrations-vercel-ai-sdk.mdx+++ b/docs/sdk/integrations-vercel-ai-sdk.mdx@@ -3,7 +3,7 @@ title: "Vercel AI SDK"description: "Use Asymptote Observe tracing with Vercel AI SDK telemetry"----## Integration Overview+## Integration overviewPass the Asymptote tracer into AI SDK telemetry so model calls and tool loops stay in the same trace.@@ -13,7 +13,7 @@ AI SDK exposes OpenTelemetry hooks through `experimental_telemetry`. Asymptote OThis page covers Node.js usage. For framework placement and serverless flushing, see [Next.js and serverless](/sdk/integrations-nextjs-serverless).-## What Asymptote Captures+## What Asymptote captures- AI SDK spans emitted when `experimental_telemetry.isEnabled` is `true`.- Model call spans for supported `generate*` and `stream*` operations.@@ -39,7 +39,7 @@ export ASYMPTOTE_API_KEY=...export OPENAI_API_KEY=...```-## Getting Started+## Getting startedInitialize `Observe` once at application startup, then pass the tracer to AI SDK calls.@@ -66,7 +66,7 @@ await Observe.flush();The same pattern applies anywhere AI SDK accepts `experimental_telemetry`.-## Reuse The Tracer+## Reuse the tracerUse `Observe.getTracer()` anywhere AI SDK accepts an OpenTelemetry tracer. This lets generated spans share the same exporter, resource attributes, and Beacon compatibility path as the rest of your application.@@ -87,7 +87,7 @@ await generateText({});```-## Trace A Tool Loop+## Trace a tool loopPass the tracer into tool-calling AI SDK flows as well.@@ -116,7 +116,7 @@ const result = await generateText({});```-## Group Calls With Custom Steps+## Group calls with custom stepsWrap orchestration code around AI SDK calls when you need spans for planning, policy checks, retrieval, or handoffs that are not covered by model telemetry.@@ -160,7 +160,7 @@ For serverless handlers, call `Observe.flush()` before returning if the invocati- In short-lived scripts or jobs, call `Observe.flush()` before exit.- In Next.js, initialize from `instrumentation.ts` in the Node.js runtime.-## What's Next+## What's next<Columns cols={2}><Card title="Next.js And Serverless" icon="cloud" href="/sdk/integrations-nextjs-serverless">diff --git a/docs/sdk/integrations.mdx b/docs/sdk/integrations.mdxindex b31089bc..a0792292 100644--- a/docs/sdk/integrations.mdx+++ b/docs/sdk/integrations.mdx@@ -3,7 +3,7 @@ title: "Agent SDK Integrations"description: "Choose an Asymptote Observe integration path for AI SDKs and agent orchestration"----## Integration Overview+## Integration overviewAsymptote Observe traces supported LLM providers, agent SDKs, and orchestration code through OpenTelemetry. Initialize `Observe`, configure the integration path for the SDK you use, and your model calls or agent turns can flow to Asymptote Managed hosted Observe or a customer-managed OTLP collector.@@ -30,7 +30,7 @@ Browse the integrations below to see setup instructions, what is captured, and t</Card></Columns>-## Shared Setup+## Shared setupAll integration paths start by installing and initializing the SDK:@@ -50,6 +50,6 @@ Observe.initialize({See the [SDK quickstart](/sdk/quickstart) for Asymptote Managed hosted Observe, customer-managed OTLP, custom exporter, and shutdown options.-## Not Supported Yet+## Not supported yetOpenAI agent-framework tracing is not documented here because the current `agent-beacon` TypeScript SDK does not ship that adapter yet.diff --git a/docs/sdk/lifecycle.mdx b/docs/sdk/lifecycle.mdxindex 38412e64..0bf657ae 100644--- a/docs/sdk/lifecycle.mdx+++ b/docs/sdk/lifecycle.mdx@@ -3,7 +3,7 @@ title: "SDK Lifecycle"description: "Flush and shut down Asymptote Observe tracing"----## Lifecycle Overview+## Lifecycle overviewUse `Observe.flush()` and `Observe.shutdown()` to control when finished spans are exported and when the SDK releases tracing resources.@@ -59,7 +59,7 @@ Observe.initialize({If the SDK is already initialized, a later `Observe.initialize({ instrumentModules })` call patches additional modules without replacing the provider.-## Short-Lived Example+## Short-lived example```typescript title="Short-lived job example" linesimport { Observe } from "@asymptote/sdk";diff --git a/docs/sdk/observe.mdx b/docs/sdk/observe.mdxindex 60eab6ef..a5eff978 100644--- a/docs/sdk/observe.mdx+++ b/docs/sdk/observe.mdx@@ -7,7 +7,7 @@ description: "Wrap custom agent functions with Asymptote Observe"Use `Observe.observe()` to create spans for custom agent orchestration: planning, tool execution, policy checks, handoffs, retrieval, and other work that provider SDKs do not expose.-## Wrap A Function+## Wrap a function```typescript title="Wrap a tool call" linesimport {@@ -39,7 +39,7 @@ await Observe.flush();The wrapped function preserves the original return behavior for sync functions, promises, and async iterables. Errors are recorded on the span and then rethrown.-## Observe Options+## Observe options| Option | Purpose || --- | --- |@@ -49,7 +49,7 @@ The wrapped function preserves the original return behavior for sync functions,| `ignoreInput` | Do not record `asymptote.observe.input.count` || `ignoreOutput` | Do not record `asymptote.observe.output.type` |-## Avoid Sensitive Metadata+## Avoid sensitive metadataSet `ignoreInput` or `ignoreOutput` when wrapper metadata should avoid recording argument counts or output type.@@ -66,7 +66,7 @@ const lookupSecretSafely = Observe.observe(Beacon compatibility attributes should still be chosen carefully. Do not place raw secrets, credentials, or high-risk prompt content in custom attributes.-## Common Beacon Actions+## Common Beacon actionsUse Beacon compatibility attributes when a custom step should normalize into a known event category.diff --git a/docs/sdk/quickstart.mdx b/docs/sdk/quickstart.mdxindex 664d9871..be1d7721 100644--- a/docs/sdk/quickstart.mdx+++ b/docs/sdk/quickstart.mdx@@ -3,7 +3,7 @@ title: "SDK Quickstart"description: "Install and initialize the Asymptote TypeScript SDK"----## Setup Flow+## Setup flowFollow this path to install `@asymptote/sdk`, initialize tracing, create a first span, and flush it before the process exits.@@ -15,7 +15,7 @@ npm install @asymptote/sdkThe package requires Node.js 20 or newer.-## 2. Configure Export+## 2. Configure exportChoose Asymptote Managed hosted Observe or a customer-managed OTLP endpoint.@@ -47,7 +47,7 @@ Hosted export uses OTLP/HTTP traces.The SDK appends `/v1/observe` when the configured base URL or endpoint does not already include it.-### Customer-Managed OTLP+### Customer-managed OTLPUse an explicit OTLP endpoint when traces should go to a local or customer-managed collector instead of Asymptote Managed hosted Observe:@@ -65,7 +65,7 @@ Observe.initialize({Explicit OTLP export does not require an Asymptote Managed API key.-## 3. Create A First Trace+## 3. Create a first traceWrap application code with `Observe.observe()` to create a Beacon-compatible span.@@ -95,7 +95,7 @@ await plan("Review this pull request");await Observe.flush();```-## Export Precedence+## Export precedence`Observe.initialize()` resolves export configuration in this order:@@ -118,7 +118,7 @@ Observe.initialize({});```-## What To Read Next+## What to read next<Columns cols={2}><Card title="Instrumentation" icon="wand-magic-sparkles" href="/sdk/instrumentation">@@ -135,7 +135,7 @@ Observe.initialize({</Card></Columns>-## Flush Before Exit+## Flush before exitFor short-lived scripts, CI jobs, and serverless handlers, flush spans before the process exits:diff --git a/docs/sdk/reference.mdx b/docs/sdk/reference.mdxindex 4936a4f6..806d8ed2 100644--- a/docs/sdk/reference.mdx+++ b/docs/sdk/reference.mdx@@ -3,7 +3,7 @@ title: "SDK Reference"description: "Asymptote Observe TypeScript API, options, and Beacon compatibility attributes"----## API Surface+## API surfaceThe TypeScript SDK exports the `Observe` class, function equivalents, and Beacon compatibility constants from `@asymptote/sdk`.@@ -24,7 +24,7 @@ For guided setup, start with [SDK Quickstart](/sdk/quickstart), [InstrumentationFunction exports are also available for the same operations, including `initialize`, `getTracer`, `observe`, `patch`, `initializeAsymptoteInstrumentations`, `wrapClaudeAgentQuery`, `flush`, `shutdown`, `isInitialized`, and `resolveExporterConfig`.-## Initialize Options+## Initialize options| Option | Purpose || --- | --- |@@ -46,7 +46,7 @@ Function exports are also available for the same operations, including `initiali`Observe.initialize()` may only be called once per process configuration. Call `Observe.shutdown()` before reinitializing with different options. A later `initialize({ instrumentModules })` call can patch additional modules without replacing the provider.-## Observe Options+## Observe options| Option | Purpose || --- | --- |@@ -56,7 +56,7 @@ Function exports are also available for the same operations, including `initiali| `ignoreInput` | Do not record `asymptote.observe.input.count` || `ignoreOutput` | Do not record `asymptote.observe.output.type` |-## Export Modes+## Export modes| Mode | How it is selected || --- | --- |@@ -64,7 +64,7 @@ Function exports are also available for the same operations, including `initiali| `otlp` | `otlpEndpoint` or `OTEL_EXPORTER_OTLP_ENDPOINT` is present || `custom` | Default exporter is disabled or a custom span exporter is provided |-## Beacon Compatibility Attributes+## Beacon compatibility attributesCloud SDKs should prefer standard OpenTelemetry attributes when they exist, especially `gen_ai.*` attributes for model and prompt metadata. Use Beacon attributes for fields that need to normalize into Beacon endpoint-style events.@@ -98,7 +98,7 @@ Cloud SDKs should prefer standard OpenTelemetry attributes when they exist, espe| `beacon.prompt.text` | Prompt text when available || `beacon.content.retention` | Content retention hint |-## SDK Metadata Attributes+## SDK metadata attributes| Attribute | Purpose || --- | --- |@@ -132,7 +132,7 @@ The wire-compatible Beacon event identity remains:}```-## Integration Pages+## Integration pages<Columns cols={2}><Card title="Anthropic" icon="robot" href="/sdk/integrations-anthropic">diff --git a/docs/security/data-flow-threat-model.mdx b/docs/security/data-flow-threat-model.mdxindex b18c2cd2..58fec6c1 100644--- a/docs/security/data-flow-threat-model.mdx+++ b/docs/security/data-flow-threat-model.mdx@@ -3,7 +3,7 @@ title: "Data Flow and Threat Model"description: "How Beacon endpoint telemetry flows locally and which risks the design addresses"----## Data Flow Overview+## Data flow overviewBeacon collects supported agent harness activity on the endpoint, normalizes it locally, and writes one JSON object per line to a local runtime log. Security teams can inspect that file locally, view it through the loopback dashboard, or forward it through customer-controlled security pipelines.@@ -18,7 +18,7 @@ flowchart LRnormalize --> optionalFalcon["Optional Falcon LogScale HEC"]```-## Data Flow+## Data flow| Step | Behavior | Boundary ||------|----------|----------|@@ -29,7 +29,7 @@ flowchart LR| Local inspection | The dashboard reads the runtime log over a loopback-only service | Local browser to local dashboard service || Optional forwarding | Wazuh, Elastic/Filebeat, Datadog Agent, Sumo Logic, Rapid7, Microsoft Sentinel, AWS S3, Google Cloud Storage, Splunk HEC, Falcon LogScale HEC, or customer-managed shippers read or receive events | Customer-managed network and SIEM boundary |-## Threat Model+## Threat model| Risk | Design response ||------|-----------------|@@ -40,7 +40,7 @@ flowchart LR| Destination credential exposure | Persistent endpoint file-based destinations tail local JSONL, so Beacon endpoint configuration does not store Elastic, Datadog, Sumo Logic, Rapid7, Microsoft Sentinel, AWS, or Google Cloud credentials. Optional Splunk and Falcon tokens live in collector configuration. Self-serve cloud-agent uploads are a separate proof-of-concept path: scoped GCS or AWS credentials are injected into the provider-managed sandbox as runtime secrets and must be rotated and access-reviewed. || Removal uncertainty | Endpoint uninstall removes managed service and configuration state, with explicit `--keep-logs` and `--keep-config` exceptions |-## Current Boundaries+## Current boundariesBeacon focuses on supported agent harness telemetry and local endpoint configuration context. It does not provide kernel or process monitoring, shell history collection, cloud audit ingestion, browser or SaaS telemetry, credential-use attribution, Datadog API export from Beacon, Sumo Logic API export from Beacon, Rapid7 API export from Beacon, or automatic mutation of Factory Droid shell profiles.diff --git a/docs/security/data-inventory.mdx b/docs/security/data-inventory.mdxindex 4eff37e8..65df7311 100644--- a/docs/security/data-inventory.mdx+++ b/docs/security/data-inventory.mdx@@ -3,11 +3,11 @@ title: "Data Inventory"description: "Runtime coverage and endpoint event fields Beacon can write"----## Data Categories+## Data categoriesBeacon writes normalized endpoint events only when supported runtimes provide telemetry through a configured local surface. Each event includes required event, endpoint, and harness context. Optional entities are present only when the source payload provides that context and the configured retention mode allows it.-## Runtime Inventory+## Runtime inventory| Agent harness | Collection path | Commonly available telemetry ||---------------|-----------------|------------------------------|@@ -25,7 +25,7 @@ Beacon writes normalized endpoint events only when supported runtimes provide te| Claude Cowork | Admin-configured OTLP | Prompt, command, tool, and file telemetry when emitted through Claude Cowork OTLP || OpenClaw Gateway | Gateway-configured OTLP/HTTP | OTLP logs, traces, and metrics from the Gateway diagnostics plugin |-## Local Inventory Metadata+## Local inventory metadata`beacon endpoint inventory` can also report local agent configuration metadata that is not emitted by a runtime event:@@ -37,7 +37,7 @@ Beacon writes normalized endpoint events only when supported runtimes provide teBy default, inventory is metadata- and hash-only. Beacon hashes config, hook, and `SKILL.md` files for change detection but does not retain file bodies, full MCP server definitions, or skill instruction bodies in inventory JSON, dashboard responses, or inventory snapshot events.-Operators can opt into capturing full definitions with the `--contents` flag (CLI) or the `include_contents` config setting (snapshot telemetry). When enabled, configs, hooks, and skills gain a redacted `content` block and MCP servers gain a full `definition` block. Captured contents always pass through local secret redaction — values under keys matching `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, `AUTH`, or `CREDENTIAL` are replaced with `***REDACTED***` — and a per-file size cap (64 KiB by default, configurable via `max_content_bytes`).+Operators can opt into capturing full definitions with the `--contents` flag (CLI) or the `include_contents` config setting (snapshot telemetry). When enabled, configs, hooks, and skills gain a redacted `content` block and MCP servers gain a full `definition` block. Captured contents always pass through local secret redaction and a per-file size cap (64 KiB by default, configurable with `max_content_bytes`). Redaction replaces values under keys matching `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, `AUTH`, or `CREDENTIAL` with `***REDACTED***`.Inventory heartbeat telemetry uses a separate local JSONL file, `inventory_state.jsonl`, so `runtime.jsonl` stays scoped to agent runtime activity. Normal hook execution can periodically write:@@ -46,7 +46,7 @@ Inventory heartbeat telemetry uses a separate local JSONL file, `inventory_stateBy default, snapshots include config-file metadata, MCP server metadata, skill metadata, and hook config metadata across supported local runtimes. They do not include skill instruction bodies, MCP secret values, full environment values, full command arguments, or unrelated config content. When `include_contents` is enabled, snapshots additionally carry redacted, size-limited `content` and `definition` blocks as described above.-## Required Fields+## Required fields| Field | Meaning ||-------|---------|@@ -61,7 +61,7 @@ By default, snapshots include config-file metadata, MCP server metadata, skill m| `endpoint` | Host and operating system context || `harness` | Runtime that produced the signal |-## Optional Entities+## Optional entities| Entity | Purpose | Common fields ||--------|---------|---------------|@@ -82,7 +82,7 @@ By default, snapshots include config-file metadata, MCP server metadata, skill mTop-level `model`, `repository`, `branch`, `message`, `raw`, and `field_truncated` fields can add shared context across entities. Content-bearing fields follow the configured retention mode.-For hook-based runtimes, `branch` is derived locally from the workspace's `.git/HEAD` file when the runtime payload does not provide one. This is a local file read only — no git command runs and nothing leaves the machine — and it can be disabled with `BEACON_DISABLE_GIT_METADATA=1`.+For hook-based runtimes, `branch` is derived locally from the workspace's `.git/HEAD` file when the runtime payload does not provide one. This is a local file read only: no git command runs and nothing leaves the machine. Disable it with `BEACON_DISABLE_GIT_METADATA=1`.OpenCode's managed plugin retains full prompt, completed assistant/reasoning,tool argument/result, command output, and diff content in local ordiff --git a/docs/security/endpoint-operations.mdx b/docs/security/endpoint-operations.mdxindex 49945722..9b622394 100644--- a/docs/security/endpoint-operations.mdx+++ b/docs/security/endpoint-operations.mdx@@ -3,11 +3,11 @@ title: "Endpoint Operations"description: "Filesystem paths, permissions, daemon behavior, network behavior, and uninstall guarantees"----## Operational Controls+## Operational controlsBeacon endpoint operations are local to the managed machine. User-mode installs use per-user paths for local evaluation. System-mode installs use root-managed paths and a LaunchDaemon for MDM or package deployments.-## Filesystem Paths+## Filesystem paths| Item | User mode | System mode ||------|-----------|-------------|@@ -42,7 +42,7 @@ System endpoint install creates root-managed runtime state:/var/log/beacon-agent/runtime.jsonl.1```-## Hook Configuration Paths+## Hook configuration paths| Runtime | User-level config | Project-level config | Hook binary | Runtime log ||---------|-------------------|----------------------|-------------|-------------|@@ -57,7 +57,7 @@ System endpoint install creates root-managed runtime state:In system mode, the hook binary is written under `/Library/Application Support/Beacon/Endpoint/hooks/` and the default runtime log is `/var/log/beacon-agent/runtime.jsonl`.-## Permissions and Daemon Behavior+## Permissions and daemon behaviorUser mode is the default for local evaluation and writes under the current user's home directory. System mode requires root, writes root-managed configuration and log paths, and loads the local collector as `com.beacon.endpoint.collector` through launchd.@@ -65,7 +65,7 @@ The system package is designed for Jamf Pro, Fleet, or another macOS MDM. It insThe active runtime log rotates when the next write would exceed 10 MiB. Beacon keeps up to five numbered local archives next to the active file, preserving the active path as the handoff point for local inspection and customer-managed shippers.-## Network Behavior+## Network behaviorNormal endpoint collection uses localhost OTLP receivers and local hook execution. Beacon does not require a hosted account, remote policy fetch, MDM API credentials, or external network connection for normal collection.@@ -89,7 +89,7 @@ Endpoint package self-updates are off by default. When an admin enablesrelease manifest and package asset URLs; normal runtime hook execution remainslocal-only.-## Uninstall Guarantees+## Uninstall guarantees`beacon endpoint uninstall` unloads the local Beacon service and removes managed endpoint files. Beacon removes files listed in its install manifest, including managed config, collector config, and service files. Unless `--keep-logs` is set, it also removes the configured runtime JSONL log.diff --git a/docs/security/index.mdx b/docs/security/index.mdxindex 209b2ec3..517bc5da 100644--- a/docs/security/index.mdx+++ b/docs/security/index.mdx@@ -7,7 +7,7 @@ Beacon gives Security and IT teams local endpoint visibility into supported [ageBeacon is local-only by default. The endpoint agent does not require a Beacon-hosted account, remote policy fetch, or external network dependency during normal collection. Use [Asymptote Managed](/deployment/managed) when you need centralized retention, search, governance, investigations, access control, or rollout support.-## Rollout Path+## Rollout path<Steps><Step title="Pilot">@@ -24,7 +24,7 @@ Beacon is local-only by default. The endpoint agent does not require a Beacon-ho</Step></Steps>-## Deployment Decisions+## Deployment decisionsBefore broad rollout, document these decisions:@@ -36,7 +36,7 @@ Before broad rollout, document these decisions:| Access and retention | Who can read local logs, how long downstream systems retain events, and which teams own review. || Managed handoff | Whether the rollout now needs centralized visibility, policy controls, investigations, SSO/RBAC, or private infrastructure. |-## Validation Signals+## Validation signalsTrack these signals in your device-management platform or operations dashboard:@@ -75,7 +75,7 @@ For command-level checks, see [Endpoint status](/cli/endpoint-status), [EndpointAlso review [Agent harness integrations](/runtimes) to confirm supported runtimes, deployment modes, storage paths, and forwarding boundaries.-## When to Move to Managed+## When to move to managedOpen Source works well when your team wants local endpoint telemetry and controls the downstream destination. Consider [Asymptote Managed](/deployment/managed) when you need:diff --git a/docs/security/policy.mdx b/docs/security/policy.mdxindex 3d05bdb6..b967a052 100644--- a/docs/security/policy.mdx+++ b/docs/security/policy.mdx@@ -3,17 +3,17 @@ title: "Security Policy"description: "Security contact, vulnerability disclosure, and release verification policy"----## Policy Controls+## Policy controlsUse this page for security contact, vulnerability disclosure, and release verification details for Beacon endpoint deployments.-## Security Contact+## Security contactReport suspected vulnerabilities or security concerns to [[email protected]](mailto:[email protected]).For non-security product support, use [[email protected]](mailto:[email protected]).-## Vulnerability Disclosure+## Vulnerability disclosureWhen reporting a vulnerability, include enough detail for the security team to reproduce and assess impact:@@ -25,7 +25,7 @@ When reporting a vulnerability, include enough detail for the security team to rAsymptote asks reporters to avoid accessing data that does not belong to them, disrupting customer systems, or publicly disclosing an issue before the security team has had time to investigate and coordinate remediation.-## Release Signing and Verification+## Release signing and verificationBeacon macOS packages for managed deployment are signed and notarized. Manual release archives include the `beacon` CLI and matching `beacon-otelcol` collector binary, with SHA-256 checksums published alongside the release.diff --git a/docs/security/retention-redaction.mdx b/docs/security/retention-redaction.mdxindex e8e722d7..143715d9 100644--- a/docs/security/retention-redaction.mdx+++ b/docs/security/retention-redaction.mdx@@ -3,11 +3,11 @@ title: "Redaction and Size Limits"description: "How Beacon handles retained content before writing endpoint events"----## Retention and Redaction+## Retention and redactionBeacon can write supported prompt, command, tool, file, approval, policy, and runtime context when a configured source runtime emits it. Before endpoint events are written to local JSONL or forwarded through configured destinations, Beacon applies redaction, sanitization, truncation, and event-size limits.-## Content Handling+## Content handling| Control | Behavior ||---------|----------|@@ -16,7 +16,7 @@ Beacon can write supported prompt, command, tool, file, approval, policy, and ru| Truncation | Oversized fields are shortened and marked with truncation metadata || Event-size limits | Events are bounded before they are written to `runtime.jsonl` or sent to configured destinations |-## Prompt Event Example+## Prompt event examplePrompt content is included only when the source runtime emits it. Secret-like values are redacted before the event is written:@@ -39,7 +39,7 @@ Prompt content is included only when the source runtime emits it. Secret-like va}```-## Command Event Example+## Command event exampleCommand events can include normalized tool and command context, with truncation metadata when fields exceed limits:@@ -65,7 +65,7 @@ Command events can include normalized tool and command context, with truncation}```-## Forwarding Implications+## Forwarding implicationsContent handling is applied before events are written to `runtime.jsonl`.File-based destinations such as Wazuh, Elastic/Filebeat, Datadog Agent customdiff --git a/docs/security/review.mdx b/docs/security/review.mdxindex dd3695b2..3530db87 100644--- a/docs/security/review.mdx+++ b/docs/security/review.mdx@@ -3,13 +3,13 @@ title: "Enterprise Security Review"description: "Procurement and security review details for Beacon endpoint telemetry"----## Review Scope+## Review scopeBeacon is designed for endpoint-local collection of supported agent harness activity. During normal collection, supported runtimes send telemetry to a localhost OpenTelemetry receiver or invoke the local `beacon-hooks` adapter. Beacon normalizes those signals into endpoint events and writes them to a local JSONL log for local review or customer-controlled forwarding.Normal hook execution has no Beacon-hosted dependency. The endpoint agent does not require a Beacon-hosted account, remote policy fetch, or external network connection to collect supported local runtime activity.-## Review Package+## Review package<Columns cols={2}><Card title="Data flow and threat model" icon="diagram-project" href="/security/data-flow-threat-model">@@ -32,7 +32,7 @@ Normal hook execution has no Beacon-hosted dependency. The endpoint agent does n</Card></Columns>-## Default Posture+## Default posture| Area | Default behavior ||------|------------------|diff --git a/docs/telemetry-schema/event-schema.mdx b/docs/telemetry-schema/event-schema.mdxindex d5fa29bd..7a8a348b 100644--- a/docs/telemetry-schema/event-schema.mdx+++ b/docs/telemetry-schema/event-schema.mdx@@ -47,16 +47,14 @@ Two optional fields carry that context.| Value | Meaning ||-------|---------|-| `observed` | The source named this action — a hook event name, a plugin event type, an explicit `event.action` attribute, or a structured attribute identifying the operation |+| `observed` | The source named this action: a hook event name, a plugin event type, an explicit `event.action` attribute, or a structured attribute identifying the operation || `inferred` | Beacon derived the action: a pattern match over free text, a fallback for an unrecognized event, or an action synthesized from an adjacent observation |The two are independent. One OTLP stream carries both kinds: a record that declares its`event.name` is `observed`, while a record carrying only prose is `inferred`. Both are`collection_method: otlp`.-Both fields are optional and omitted rather than written empty. Events Beacon emits about itself —-health heartbeats, self-update results — have no collecting harness and no source action to be-faithful to, so they carry neither.+Both fields are optional, and omitted rather than written empty. Events Beacon emits about itself, such as health heartbeats and self-update results, have no collecting harness and no source action to be faithful to, so they carry neither.Rules can match on both, so a detection that needs certainty can require it:@@ -80,11 +78,11 @@ call was seen. Anything counting real operator decisions should exclude them.| `event.kind` | Event family, currently `agent_runtime` || `event.action` | Normalized action such as `command.executed` or `tool.invoked` || `event.category` | Event category, provided by the runtime or inferred from `event.action` when possible |-| `event.fidelity` | Optional. `observed` or `inferred` — see [Provenance](#provenance-how-beacon-knows-what-it-wrote) |+| `event.fidelity` | Optional. `observed` or `inferred`. See [Provenance](#provenance-how-beacon-knows-what-it-wrote) || `severity` | `info`, `low`, `medium`, `high`, or `critical` || `endpoint` | Host and operating system context || `harness` | Runtime that produced the signal |-| `harness.collection_method` | Optional. `hook`, `plugin`, `otlp`, or `poll` — see [Provenance](#provenance-how-beacon-knows-what-it-wrote) |+| `harness.collection_method` | Optional. `hook`, `plugin`, `otlp`, or `poll`. See [Provenance](#provenance-how-beacon-knows-what-it-wrote) |`event.id` is written alongside these: a deterministic UUID identifying the event, described under[event identity](/telemetry-schema/normalization#event-identity). It is not required, so events@@ -104,7 +102,7 @@ schema carries two ordering fields.fresh short-lived process per hook and the collector exporter runs as one long-lived exportloop, so neither can see the other's counter, and a hook event numbered 1 may well havehappened after an exporter event numbered 900. Order by `timestamp` first and use-`sequence` only to separate events that tie on it — most often the datapoints of a single+`sequence` only to separate events that tie on it, most often the datapoints of a singlemetric export, which all carry that export's collection instant.Do not order events by their position in the log. Append order is not emission order: adiff --git a/docs/telemetry-schema/examples.mdx b/docs/telemetry-schema/examples.mdxindex 98b4920c..dec07a3e 100644--- a/docs/telemetry-schema/examples.mdx+++ b/docs/telemetry-schema/examples.mdx@@ -3,7 +3,7 @@ title: "Schema Examples"description: "Example Beacon events and content handling behavior"----## Event Examples+## Event examplesBeacon writes events as JSONL records. Each line is a complete JSON object that follows the [Unified Telemetry Schema](/telemetry-schema/event-schema).diff --git a/docs/telemetry-schema/fields.mdx b/docs/telemetry-schema/fields.mdxindex 67ea128c..0201439b 100644--- a/docs/telemetry-schema/fields.mdx+++ b/docs/telemetry-schema/fields.mdx@@ -3,7 +3,7 @@ title: "Schema Fields"description: "Beacon event entities, optional context, and shared fields"----## Field Reference+## Field referenceBeacon models each event as an action plus a set of typed entities. The [`event` object and surrounding entities](/concepts/core-concepts#entity-model) describe what happened and who or what participated in that action.@@ -38,7 +38,7 @@ Top-level `sequence`, `model`, `repository`, `branch`, `message`, `raw`, and `fi`sequence` is the emitting writer's monotonic emission counter, used to order events that share a timestamp. See [event ordering](/telemetry-schema/event-schema#event-ordering) for what it does and does not compare across.-For hook-based runtimes, when the runtime payload does not supply a branch, Beacon fills `branch` from the working directory's git checkout by reading `.git/HEAD` directly — no git binary is required, and the field is omitted when the directory is not a git repository or HEAD is detached. Set `BEACON_DISABLE_GIT_METADATA=1` (accepts `1`, `true`, or `yes`) in the runtime's environment to turn off local git metadata enrichment; runtime-provided branch values still pass through.+For hook-based runtimes, when the runtime payload does not supply a branch, Beacon fills `branch` from the working directory's git checkout by reading `.git/HEAD` directly. No git binary is required, and the field is omitted when the directory is not a git repository or HEAD is detached. Set `BEACON_DISABLE_GIT_METADATA=1` (accepts `1`, `true`, or `yes`) in the runtime's environment to turn off local git metadata enrichment; runtime-provided branch values still pass through.## GenAI contextdiff --git a/docs/telemetry-schema/normalization.mdx b/docs/telemetry-schema/normalization.mdxindex e4d559fe..eb597a3e 100644--- a/docs/telemetry-schema/normalization.mdx+++ b/docs/telemetry-schema/normalization.mdx@@ -3,7 +3,7 @@ title: "Schema Normalization"description: "How Beacon maps OTLP attributes and hook payloads into normalized events"----## Normalization Rules+## Normalization rulesBeacon normalizes [OTLP](/concepts/core-concepts#otlp) attributes and [hook](/concepts/core-concepts#hooks) payloads into the same event contract. The collector exporter looks for common runtime fields, while hook telemetry builds those fields directly from hook payloads.@@ -104,7 +104,7 @@ one, they describe one call, and the writer records that call once rather than t`event.id` is Beacon's own identity for the event: a deterministic UUID, so the same event isnamed the same way in any process and any release. Where the runtime named the action itself, the-UUID is derived from the session, action, target and call ID, and nothing else — so the hook's+UUID is derived from the session, action, target, and call ID, and nothing else, so the hook'sreport and the collector's report of one action carry one `event.id` even though they are writtenseconds apart with different fields. Otherwise it is derived from the event's own content, whichmakes re-reading a log produce the IDs it already had.