Rules for agents using Insider, a runtime-evidence library for BEAM
applications, built for coding agents.
Short on purpose. Each rule names its guide: deps/insider/guides/<path>.md
in a host app, or guides/ in an Insider checkout.
Where the docs are
deps/insider/guides/agents/*.mdand this file: the guides for exactly the Insider the app uses. With apath:dependency, read that checkout'sguides/instead.- On a running node, the welcome document is the authoritative contract:
Insider.Live.welcome()/Insider.Live.JSON.welcome()(the quick start;%{"full" => true}for the full reference), ormix insider.live welcome --node … --cookie-file …(--full) from the Insider checkout'stools/insider_lab, orinsider-lab live welcome …aftermix escript.install hex insider_lab. deps/insider/docs/README.md(ordocs/README.mdin a checkout) indexes the full reference. Its task table names the one section to read for a task, with its size. The guides point into it.
Live observation
- Read the welcome quick start before anything else and keep its
hash;capabilitiesreports the current hash. Read--fullwhen you need an option's exact syntax or an error code. Seeguides/agents/live-observation.md. - Live observation works only where the node resolves to development, test, or ci. Never try to assert or work around the environment.
- One session per node. Start with the fewest components that can show the
effect, then act,
digestthe session for the overview, and readevents_sincefrom your cursor for detail, keepingnext_cursor. Non-emptygapsmeans evidence was lost. - Reads renew the lease;
statusand subscriptions do not.stopwhen done and check the receipt. - Sharing a node with other agents: pass
--reader NAMEto reads, watches, stops and amends;amendchanges recording options for everyone without losing history; never--forcea stop over a peer's active reads without asking. Concurrent agents use the escript (./insider-lab live). - Disclosure depends on the node's profile. Check the welcome's
effective_disclosure.profile(alsoruntime.disclosure_profile) before you rely on any payload. Development and test default torich: events carry Logger message text and metadata, Telemetry metadata and measurements, with credentials masked. In thestrictprofile (the ci default, orconfig :insider, :live_disclosure, :strict), event payloads, Logger message text, and Telemetry metadata never leave the node. In either profile, do not try to recover what was withheld or masked another way. See the welcome'sdisclosurerules.
Reporting Insider's own bugs
- You must report Insider bugs and every behaviour that differs from the
welcome document:
mix insider.live report --category doc_mismatch --message '…', orInsider.Live.JSON.report(%{"category" => …, "message" => …}). Categories:bug,doc_mismatch,missing_capability,confusing_output. - Say what you expected (cite the welcome field) and what happened. Never put payloads, log text, option values, or secrets in a report.
- Reports stay local. Only the developer sends them upstream, with
mix insider.live reports submit --confirm.reports submit --dry-runonly previews, whatever opt-in is set. Cite your session withreport --session ID;reportsgroups the shared queue by node and session.
Other agent tooling
- ExUnit candidates and oracles:
guides/agents/candidates-cli.md,guides/agents/oracles.md. - What Insider refuses to do, and why:
guides/agents/refusals.md. Stop at a refusal; do not look for a weaker path.