This is the index of Insider's reference documentation. The README is the short synopsis. The cheat sheet has the commands you use most, and the glossary defines the terms.
Contents
- How to use this index
- Use Insider Live
- Lab and research
- Production readiness and development
- Files
- Other documents
How to use this index
- Find your task in one of the three tables below. Read only the section it names. A section runs from its heading to the next heading of the same or a higher level.
- Use the anchors as stable references. Line numbers change with every edit, so this index does not give them.
- The sizes are approximate line counts of the section, including its subsections. No linked section is longer than 150 lines. A test checks both.
- Each topic file starts with links back to this index, the glossary and the cheat sheet, then its own contents list.
- On a running node, the welcome document is the authority for the Insider
that is loaded. Where it and these files differ, trust the welcome and file
a
doc_mismatchreport.
Use Insider Live
Live observation of a running development, test or ci node. This is what the README describes.
| If you need to … | Read | Size |
|---|---|---|
| Run the commands you use most | Cheat sheet | ~115 lines |
| Look up a term | Glossary | ~265 lines |
| Install the CLI from Hex, or add Insider to your app | Install the CLI, Add Insider to your app | ~16 + ~22 lines |
| Make first contact with a node you start | Observe a running node in five minutes | ~112 lines |
| Make first contact with a node you did not start | Attach to a node you did not start, then Load Insider into the target | ~18 + ~29 lines |
| Know what the welcome document gives an agent | Welcome document | ~67 lines |
| Find the commands for a symptom | Welcome recipes | ~62 lines |
| Get the short operating contract for live observation | Live observation guide | ~190 lines |
Choose an Insider.Live function or start option | Live observation | ~109 lines |
| Know who may observe a node, and for how long | Environment and ownership, Lease | ~17 + ~17 lines |
| Look up an observer flag | Observer flag reference, Recording flags, Read flags | ~48 + ~27 + ~33 lines |
Read without passing --session | Default session | ~13 lines |
| Understand an exit status or observer error | Exit statuses and error codes | ~46 lines |
| Run several agents at once | Several agents at once: the escript, then Several agents on one session | ~14 + ~115 lines |
Observe through Tidewave project_eval | Tidewave project_eval | ~31 lines |
| Stop a session and check what was cleaned up | Stop and check the cleanup receipt | ~37 lines |
| Pair with a programmer who acts in the app | Pairing marks, then Digest | ~41 + ~136 lines |
| Show the programmer you pair with a chart of the session | Pairing chart | ~46 lines |
| See what is wrong on the node right now | Digest | ~136 lines |
| Follow a digest hint | Digest hints and text | ~71 lines |
| Hide anomalies you already know about | Known-normal baseline | ~33 lines |
| See how a series moved over time | Summary trends | ~76 lines |
| Pages hang, but each request looks fast | Request waits and bursts, then One-shot inspections | ~46 + ~136 lines |
| Investigate a stuck process or a growing mailbox | One-shot inspections, Process and ETS evidence | ~136 + ~116 lines |
| Read one request as a trace | Read one request as a trace | ~80 lines |
| Keep a trace past eviction | Pin a trace | ~52 lines |
| See the values a GraphQL response returned | Response values | ~42 lines |
| Find an N+1 or a repeated query | Repeated query shapes | ~49 lines |
| Follow an Oban job | Oban jobs | ~17 lines |
| See everything one process or request did | Timeline of a process or request | ~19 lines |
| Find who sent a GraphQL request or mutation | GraphQL outcome, Kept mutation records | ~64 + ~37 lines |
| Find who changed an in-memory value | Changes of in-memory values | ~71 lines |
| See the arguments of calls to one function | Call traces | ~132 lines |
| Join a frontend's spans to the backend's | Frontend traces | ~56 lines |
| Record the node's OpenTelemetry spans | OpenTelemetry spans and traces | ~90 lines |
| Find which Telemetry events a node emits | Telemetry discovery | ~88 lines |
| Read events without missing any | Cursors and gaps | ~111 lines |
| Understand a gap or an empty read | Gaps, Filtered counts, Per-reader views | ~47 + ~20 + ~12 lines |
| Change what a running session records | Live amendment | ~24 lines |
| Quiet a noisy development server | Filters, summaries, and views | ~108 lines |
| Know what each disclosure profile shows and withholds | What each profile shows and withholds | ~89 lines |
| Know how credentials are masked | Credential masking | ~82 lines |
| Know why something was refused | Error codes, then the refusals guide | ~89 lines |
| Report a bug in Insider | Agent reports | ~118 lines |
| Explain the safety model to a person | The safety model guide | ~114 lines |
| Know where production stops | Production boundary | ~21 lines |
Lab and research
The Lab is a separate Mix project, published to Hex as insider_lab. Its
tools and the Sentinel chain run only in development and disposable
environments.
| If you need to … | Read | Size |
|---|---|---|
| Chase a flaky test, or run one repeatedly | Flaky tests: what Insider offers | ~32 lines |
| Find test-isolation candidates | Agent-requested ExUnit candidates | ~120 lines |
| Confirm a candidate with an oracle | Application-env oracle, Handler and global-state oracles, Oracle runner | ~93 + ~122 + ~78 lines |
| Check who may perform an operation, or a retry after a fault | Probe-library oracles | ~72 lines |
Drive mix insider or the Lab escript | Lab CLI transport | ~84 lines |
| Check that a privacy corpus leaks nothing | Privacy corpus runner | ~56 lines |
| Understand clean-target reproduction | Collector-to-Sentinel handoff, Confirmation and verification | ~81 + ~94 lines |
| Shrink or bisect a reproduction | Regression and minimization, Bisection | ~63 + ~69 lines |
| Follow the offline repair chain | Proof workflow | ~127 lines |
| Check an incident capsule or its provenance | Incident capsules, Portable provenance | ~34 + ~14 lines |
| Run a supervised collector session in a host app | Supervised collector sessions | ~111 lines |
| Know which detectors exist today | Detection goals | ~21 lines |
Production readiness and development
Production readiness work grants no authority: staging and production observation stay denied.
| If you need to … | Read | Size |
|---|---|---|
| Understand how the parts fit | Architecture | ~140 lines |
| Know what is implemented today | Current status, Live observation status, Lab investigation status | ~42 + ~78 + ~59 lines |
| Know what the roadmap plans | Roadmap | ~26 lines |
| Contribute code | Checks and gates and Repository layout, after AGENTS.md | ~49 + ~27 lines |
| Find load and soak evidence | Synthetic load and soak evidence | ~22 lines |
| Release a version to Hex | Releasing | ~98 lines |
Files
| File | What it holds | Size |
|---|---|---|
| Getting started | Installing the CLI, the five-minute quick start, a node you did not start, the Tidewave variant, adding Insider to your app, repository setup, and a host AGENTS.md snippet. | ~207 lines |
| Cheat sheet | The most-used observer commands, by task. | ~115 lines |
| Glossary | Terms, and the ones that mean different things in Live, the Lab and the load harness. | ~265 lines |
| Insider Live: API and transports | Functions and start options, environment, lease, cleanup receipt, Tidewave, and the observer node and its flags. | ~580 lines |
| Insider Live: sessions, readers and marks | Cursors and gaps, Recorder shares, subscriptions, several readers, amendment, handoff, marks, the pairing chart, and event time. | ~483 lines |
| Insider Live: digest, filters and trends | The digest, its hints and baseline, summary trends, filters, summaries, views, and severity. | ~580 lines |
| Insider Live: processes, calls and Telemetry | Process and ETS rankings, one-shot inspections, call traces, changes of in-memory values, and Telemetry discovery. | ~585 lines |
| Insider Live: OpenTelemetry traces and GraphQL | Spans, traces, query shapes, Oban jobs, pinned traces, response values, mutation records, timelines, request waits, the GraphQL outcome, and the OTLP receiver. | ~585 lines |
| Insider Live: welcome, reports and error codes | The welcome document and its recipes, agent reports, and the error-code vocabulary. | ~435 lines |
| Disclosure and safety | The production boundary, profiles and what each withholds, rich rendering, credential masking, redaction, and non-goals. | ~390 lines |
| Collectors and detectors | The signals Insider reads, supervised collector sessions, the system-event collector, detectors, contracts, polling, and the same-node diagnostic API. | ~450 lines |
| Lab: ExUnit candidates and oracles | The candidate inventory, the value-free oracles, the oracle runner, probe-library oracles, and flaky tests. | ~545 lines |
| Lab: CLI transport and privacy corpus | mix insider, the escript, acceptance hosts, the Recorder, collectors, ingress profiles, and the privacy corpus runner. | ~500 lines |
| Sentinel and the proof workflow | Confirmation, verification, regression, minimization, bisection, the offline repair chain, and deduplication. | ~600 lines |
| Incident capsules and provenance | Capsules, provenance, and the inert observability trigger and export. | ~115 lines |
| Architecture | Purpose and the intended loop, the trust boundary, module boundaries, and the production artifact boundary. | ~140 lines |
| Development | Repository layout, checks and gates, load and soak evidence, documentation tooling, and releasing to Hex. | ~276 lines |
| Status and roadmap | What is implemented, as tables, and the roadmap phases. | ~220 lines |
Other documents
- Guides: short curated entry points for people (
guides/people/) and agents (guides/agents/). Start with the overview or the live observation guide. usage-rules.md: the short rules for agents in a host app.- Production readiness, which grants no authority: the threat model, the readiness dossier, and the staged-canary runbook.
AGENTS.md: rules for contributors and coding agents.CHANGELOG.md: release-facing changes.- Decision log: append-only records of trust, packaging, authority and protocol decisions.
- Lab README and Load README: the Lab, published to Hex, and the Load project, which is not.