failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/agenteye/event-stream.mdx

@@ -0,0 +1,50 @@
+---
+title: "Event Stream"
+description: "The moment your agent does something, you see it."
+---
+
+
+The moment your agent does something, you see it. The Event Stream is your live pulse on every agent in production: no waiting, no grepping logs, no guessing what just happened.
+
+![The live Event Stream: colour-coded event rows tailing in real time, filterable by environment, agent, session, event type, and free text](/agenteye/images/events-stream.png)
+
+*Every event from every agent in your org, newest first, updating as it happens.*
+
+## Your live pulse on every agent
+
+When an agent starts a run, calls a model, fires a tool, runs a hook, or hits an error, the row appears at the top of the stream the moment it happens. It tails every event across every agent in your organization, newest first, so you always have a current picture instead of a stale one.
+
+That means no tailing log files on a box somewhere, no grepping across machines, no stitching timestamps together by hand. You open one page and you are already watching production.
+
+Rows are colour-coded by type, so you can read the stream at a glance instead of parsing every line. At a glance, each row shows you:
+
+- **Its type**, colour-coded: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, and more.
+- **A one-line summary** of what happened, so you rarely need to open anything just to get the gist.
+- **Token counts** for the step.
+- **A context-window fill badge** where it applies, so prompt growth and an approaching compaction are visible before they bite.
+
+Watching it live means you catch a bad deploy, a runaway loop, or a burst of errors as it happens, not in tomorrow's log review.
+
+## Find the one run that matters
+
+When something looks off, you don't want the firehose. You want the single run that broke. The stream filters down fast: by environment, by agent, by session, by event type, or by free text.
+
+Filter by session id or agent id to follow one run from its first event to its last. Filter by event type to isolate a single kind of activity, for example every `error` across the org in one view. Stack filters to narrow from "everything, everywhere" to "this agent, in prod, erroring" in a couple of clicks, then act on what you find.
+
+Free-text search cuts straight to a message, a tool name, or an id you already have in hand, so a customer report turns into the exact run in seconds.
+
+## Where to find it
+
+The Event Stream is your org home. Sign in and it is the first surface you land on, at `/<org-slug>/`, so triage starts the second you arrive.
+
+Behind it, your agents emit events through the SDK, the collector ships them to your Failproof AI Observability server, and the stream tails them as they arrive in infrastructure you control. When you want the rolled-up view instead of the raw trail, each run's events collapse into a single row on Sessions, one click away.
+
+This is the raw source of truth that every other observe surface builds on, so when a number looks wrong elsewhere, the stream is where you confirm what actually happened.
+
+## Related
+
+- [Sessions](/agenteye/sessions): the same events rolled up into one row per run, with a git-style execution graph.
+- [Telemetry](/agenteye/telemetry): what your agents send and how events reach the stream.
+- [Error tracking](/agenteye/error-tracking): one triage surface for everything that went wrong.
+- [Alerts](/agenteye/alerts): turn any threshold into a paging rule.
+- [CLI and agents](/agenteye/cli-and-agents): the same live trail from your terminal.

package/.next/standalone/docs-old/agenteye/hermes-capture.mdx

@@ -0,0 +1,53 @@
+---
+title: "Hermes session capture"
+description: "Bring your team's Hermes gateway sessions — Slack, Telegram, CLI, and scheduled runs — into AgentEye as ordinary sessions and events."
+---
+
+[Hermes](https://hermes-agent.nousresearch.com) answers your team from wherever they already work — Slack, Telegram, the CLI, scheduled runs. Hermes session capture brings all of it into AgentEye as ordinary sessions and events, so the assistant your team talks to every day is as observable as the agents you write yourself.
+
+A small background collector reads Hermes's local session store as it is written and ships sessions to AgentEye. It works the same way as [Codex](/agenteye/codex-capture) and [OpenClaw](/agenteye/openclaw-capture) capture, and one collector can capture several at once.
+
+---
+
+## What it captures
+
+Every Hermes session on the machine is captured, whichever channel it came from. Each one becomes an AgentEye [session](/agenteye/sessions); its user and assistant messages, tool calls, and tool results become the matching [events](/agenteye/event-stream).
+
+The channel a session started from — Slack, Telegram, CLI, or a scheduled run — is recorded on the session, so you can tell them apart and filter to one at a time. Alongside it come the model the session ran on, the chat and person it was started from, and, when a session spawned another, the link back to its parent.
+
+Sessions appear as soon as Hermes starts them, whether or not anything has been said yet, and a turn's reply and its tool calls stay in the order they actually happened. When a session ends you also get why it ended, what it cost, and how many tokens it used.
+
+---
+
+## Turn it on
+
+Capture is off until you enable it. Install the collector with an API key that has the `events:add` permission (see [API keys](/agenteye/api-keys)), and turn on Hermes capture:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --hermes-enabled
+```
+
+That installs the collector, registers it as a background service, and starts capturing. Confirm it is running:
+
+```bash
+agenteye-collector health
+```
+
+Capturing more than one agent on the same machine? Add each one's flag to the same command — for example `--hermes-enabled --codex-enabled`.
+
+On first run, your existing Hermes sessions are backfilled once and new activity then streams within seconds. Hermes's own data is only ever read — never modified or deleted — and each message is shipped once, even across restarts.
+
+`health` also tells you whether everything the collector captured actually reached AgentEye. If a batch could not be delivered it is kept and retried rather than discarded, and the check reports unhealthy while anything is still outstanding — so "healthy" means your data arrived, not merely that the process is alive.
+
+---
+
+## Where it shows up
+
+Captured sessions appear in **Sessions**, and their events in the **Events** stream, the same as any other agent you observe — so [session replay](/agenteye/sessions), [search](/agenteye/queries), [evaluations](/agenteye/evaluations), and [alerts](/agenteye/alerts) all work on them. Filter by the Hermes agent to see them on their own.
+
+---
+
+## Privacy
+
+Hermes sessions contain the full transcript — including command output, file contents, and anything the agent read or wrote — and can contain secrets. Captured sessions are shipped as-is, so enable capture only where centralizing that content in AgentEye is appropriate, and give the collector a key scoped to `events:add` only. See [Security](/agenteye/security) for how your data is kept isolated.

package/.next/standalone/docs-old/agenteye/incidents.mdx

@@ -0,0 +1,50 @@
+---
+title: "Incidents"
+description: "When an alert fires, everyone can see the incident is open, who owns it, and what has happened so far — on one attributed timeline."
+---
+
+
+When an alert fires, the first question is always "who's on it?" Incidents answer it: the moment something breaches, everyone can see the incident is open, who owns it, and exactly what has happened so far, with a clean, attributed record you can hand straight to a post-mortem.
+
+![The Incidents inbox: alert-linked and manually opened incident cards, grouped by state, each with a severity badge and an assignee](/agenteye/images/incidents.png)
+*The inbox groups open incidents by state and filters by severity and assignee, so you see what needs a human now.*
+
+## Know who has it, at a glance
+
+No more "is anyone looking at this?" in a chat thread. A breach opens an incident automatically and drops it into a shared inbox, grouped by state. Acknowledge it and your name is on it, so the rest of the team knows it is handled. Acknowledgement is shared: several operators can ack the same incident and each is recorded on its own, so a full war room shows up by name instead of stepping on each other. Assign one owner for triage, and filter the inbox by severity or assignee to cut it down to what is yours.
+
+## The whole story, in one timeline
+
+When the incident is over, you already have the write-up. Open any incident and you get the breach evidence, its assignees and subscribers, a comment thread for coordinating in place, and an append-only activity timeline.
+
+![An incident detail view: the parent alert and breach summary, assignees and subscribers, an attributed activity timeline, and a comment thread](/agenteye/images/incident-detail.png)
+*Everything that happened, in order, each line signed by whoever did it.*
+
+Every action (opened, acknowledged, resolved, and so on) is written to that timeline and never edited away. Each entry is attributed: to the operator who took it, by email, or to **automated** for anything Failproof AI Observability did on its own, like opening the incident on the breach. Nothing is anonymous and nothing is lost, so the post-mortem more or less writes itself.
+
+## How an incident moves
+
+```mermaid
+stateDiagram-v2
+    [*] --> firing
+    firing --> acknowledged: an operator acks
+    firing --> resolved: an operator resolves
+    acknowledged --> resolved: an operator resolves
+    resolved --> [*]
+```
+
+- **Open (firing):** the breach opens the incident and pages your channels once. Repeated breaches fold into the same incident and refresh its evidence instead of paging you again and again.
+- **Acknowledged:** an operator picks it up. It stays open, and later breaches update the evidence quietly.
+- **Resolved:** an operator closes it out. Automatic resolution when the condition clears is planned but not yet enabled, so an incident stays open until a human resolves it, which keeps everyone honest about what has actually cleared. A fresh incident can open on the same alert later.
+
+One alert holds at most one open incident at a time, so a flapping rule cannot bury you in duplicates. You can also open an incident by hand: a standalone one for something no alert caught, or one attached to an existing alert, if you have `incidents:write`.
+
+## Where to find it
+
+Incidents live at `/<org-slug>/incidents`. Viewing needs **`incidents:read`**; opening a manual incident needs **`incidents:write`**; acknowledging, assigning, commenting, and resolving need **`incidents:ack`**. Older keys granted the retired `alerts:ack` keep working, since it is honored as `incidents:ack`, so your on-call rotation does not need re-issuing.
+
+## Related
+
+- [Alerts](/agenteye/alerts): the rules that open these incidents when a threshold breaches.
+- [Error tracking](/agenteye/error-tracking): see every failure in one place and promote one to an alert.
+- [Audits](/agenteye/audits): the scheduled analyst that finds the failures no rule was watching.

package/.next/standalone/docs-old/agenteye/observability.mdx

@@ -0,0 +1,23 @@
+---
+title: "Observe"
+description: "The observe surfaces are where you watch what your agents are doing right now and drill into any single run."
+---
+
+
+The observe surfaces are where you watch what your agents are doing right now and drill into any single run. Everything here is live, scoped to your organization, and filterable by date range, environment, agent, and session, so you go from "something feels off" to the exact run in seconds.
+
+![The live Event Stream, colour-coded by type and filterable by environment, agent, and session](/agenteye/images/events-stream.png)
+
+Four surfaces, each with its own page:
+
+- **[Event stream](/agenteye/event-stream)**: the live, per-step trail of every run across every agent, newest first. Your org home and first stop for triage.
+- **[Sessions and execution graph](/agenteye/sessions)**: those events rolled up into one row per run, plus a git-style picture of how each run unfolded.
+- **[Performance metrics](/agenteye/telemetry)**: latency heat-maps and p50/p95/p99 vitals for your models, tools, and hooks, so a tail spike stands out from the median.
+- **[Error tracking](/agenteye/error-tracking)**: one triage surface for everything that went wrong, one click from a firing alert to the run that broke.
+
+## Related
+
+- [Evaluations](/agenteye/evaluations): score every run for quality.
+- [Alerts](/agenteye/alerts): turn any threshold into a paging rule.
+- [Audits](/agenteye/audits): let Failproof AI Observability find failure patterns across sessions for you.
+- [CLI and agents](/agenteye/cli-and-agents): the same observability from your terminal.

package/.next/standalone/docs-old/agenteye/openclaw-capture.mdx

@@ -0,0 +1,49 @@
+---
+title: "OpenClaw session capture"
+description: "Tail your team's local OpenClaw sessions into AgentEye as ordinary sessions and events — with no change to how OpenClaw runs."
+---
+
+If your team runs [OpenClaw](https://docs.openclaw.ai), OpenClaw session capture brings those sessions into AgentEye as ordinary sessions and events, so you can search, replay, and evaluate them next to everything else you observe. It complements the [Python SDK](/agenteye/python-sdk): the SDK instruments agents you write, while this captures the OpenClaw work your team already does — with no change to how they run it.
+
+A small background collector reads OpenClaw's local session transcripts as they are written and ships them to AgentEye. It works the same way as [Codex capture](/agenteye/codex-capture), and one collector can capture both at once.
+
+---
+
+## What it captures
+
+Every agent configured in a machine's OpenClaw setup is captured by that machine's collector — there is no per-agent setup.
+
+Each OpenClaw session becomes an AgentEye [session](/agenteye/sessions); its user and assistant messages, tool calls, and tool results become the matching [events](/agenteye/event-stream).
+
+---
+
+## Turn it on
+
+Capture is off until you enable it. Install the collector with an API key that has the `events:add` permission (see [API keys](/agenteye/api-keys)), and turn on OpenClaw capture:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --openclaw-enabled
+```
+
+That installs the collector, registers it as a background service, and starts capturing. Confirm it is running:
+
+```bash
+agenteye-collector health
+```
+
+Capturing more than one agent on the same machine? Add each one's flag to the same command — for example `--openclaw-enabled --codex-enabled`.
+
+On first run, your existing OpenClaw sessions are backfilled once and new activity then streams within seconds. OpenClaw's own files are only ever read — never modified, moved, or deleted — and each session is shipped exactly once, even across restarts.
+
+---
+
+## Where it shows up
+
+Captured sessions appear in **Sessions**, and their events in the **Events** stream, the same as any other agent you observe — so [session replay](/agenteye/sessions), [search](/agenteye/queries), [evaluations](/agenteye/evaluations), and [alerts](/agenteye/alerts) all work on them. Filter by the OpenClaw agent to see them on their own.
+
+---
+
+## Privacy
+
+OpenClaw transcripts contain the full session — including command output, file contents, and anything the agent read or wrote — and can contain secrets. Captured sessions are shipped as-is, so enable capture only on machines and for teams where centralizing that content in AgentEye is appropriate, and give the collector a key scoped to `events:add` only. See [Security](/agenteye/security) for how your data is kept isolated.

package/.next/standalone/docs-old/agenteye/overview.mdx

@@ -0,0 +1,108 @@
+---
+title: "Failproof AI: Observe Agents for Failures"
+description: "Failproof AI Observability is a self-hosted platform for observing, evaluating, and improving your AI agents in production."
+---
+
+
+Failproof AI Observability is a self-hosted platform for observing, evaluating, and improving your AI agents in production. It records everything your agents do (every tool call, model request, hook, and error), scores the quality of each run, and surfaces the failures you didn't know to look for, all in a dashboard you run inside your own infrastructure.
+
+If you ship AI agents and you're tired of guessing why a run went wrong, this is the page to start on. It explains what Failproof AI Observability gives you and how the pieces fit together, before you install anything.
+
+> **Failproof AI Observability is an enterprise product from Failproof AI.** Want to see it in action? Request a demo: email [nikita@befailproof.ai](mailto:nikita@befailproof.ai).
+
+![A Failproof AI Observability session drawn as a git-style execution graph beside its event timeline, with a per-run breakdown of tools, models, and hooks in the right rail](/agenteye/images/session-detail.png)
+
+*Every agent run is drawn as a git-style execution graph (left) beside its event timeline. Parallel sub-agents each get their own lane; the right rail breaks down the tools, models, hooks, and token spend for the run.*
+
+---
+
+## See it in action
+
+Two short videos show the two things teams reach for first: tracing a run, and finding failures automatically.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Agent tracing: follow a single run step by step, from goal to tools to final answer.*
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/C5nHKGQIqZQ?autoplay=1&mute=1&loop=1&playlist=C5nHKGQIqZQ&rel=0&playsinline=1" title="Watch: Automatically find where your agent is failing (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Failproof Audit: let Failproof AI Observability mine your logs across sessions and tell you what to fix.*
+
+---
+
+## Why teams use it
+
+- **See what your agent actually did.** Every run becomes a readable, git-style execution graph: which tools ran in parallel, which sub-agents branched off, where it stalled, and what it spent.
+- **Catch quality regressions automatically.** Connect a small scoring service and Failproof AI Observability scores every finished run, so a drop in helpfulness or a spike in hallucinations shows up on its own.
+- **Find failures you didn't write a rule for.** Recurring audits mine your logs across sessions for error clusters, latency outliers, low scores, and stuck runs, then hand you ranked, evidence-backed findings.
+- **Get paged when it matters.** Threshold rules fire on error rate, latency, cost, or evaluator scores and open incidents you can acknowledge, assign, and resolve.
+- **Ask questions in plain English.** An in-dashboard AI assistant answers "how is quality trending in prod this week?" over your own data. Any change it makes is approval-gated.
+- **Keep your data.** Failproof AI Observability is self-hosted: events, prompts, and analytics stay in infrastructure you control.
+
+---
+
+## What you get
+
+Failproof AI Observability is organized around three ideas (**observe**, **analyze**, and **admin**), mirrored in the dashboard's left sidebar.
+
+**Observe** (the raw truth of what happened):
+
+- **[Event stream](/agenteye/event-stream)**: the live, per-step trail of every run (tool calls, model calls, hooks, errors).
+- **[Sessions](/agenteye/sessions)**: those events rolled up into one row per run, each ready to be scored, with a git-style execution graph.
+- **[Performance metrics](/agenteye/telemetry)**: per-surface latency heat-maps and p50/p95/p99 vitals for models, tools, and hooks, so a tail spike stands out from the median.
+- **[Error tracking](/agenteye/error-tracking)**: one triage surface for everything that went wrong, one click from a firing alert.
+
+![The Tools observe page: a latency heat-map, a percentile band, and a tool-distribution bar over 24 time bins](/agenteye/images/tools.png)
+
+*Each observe surface pairs a sparkline and p50/p95/p99 vitals with a latency heat-map and a percentile band. Shown here: Tools.*
+
+**Analyze** (turn activity into answers):
+
+- **[Queries](/agenteye/queries)** and **[dashboards](/agenteye/dashboards)**: saved SQL over your events and evaluations, charted into shared, org-scoped dashboards.
+- **[Evaluations](/agenteye/evaluations)**: quality scores produced by your own evaluator service, with per-score reasoning.
+- **[Audits](/agenteye/audits)**: recurring investigations that surface failure patterns across sessions.
+- **[Alerts](/agenteye/alerts)** and **[incidents](/agenteye/incidents)**: threshold rules that page you, plus an incident workflow to triage them.
+
+**Interfaces** (reach your data your way):
+
+- **[CLI](/agenteye/cli-and-agents)**: drive your whole deployment from the terminal or a script, and let a coding agent do it for you in plain English.
+- **[AI assistant](/agenteye/assistant)**: ask questions about your agents in plain English, right inside the dashboard.
+- **REST API**: everything the dashboard and CLI do is backed by a REST API you can call directly with a scoped [API key](/agenteye/api-keys) — ingest events, query sessions and evaluations, and manage dashboards, alerts, audits, users, and keys, so you can wire Failproof AI Observability into your own tooling.
+
+**Admin** (run it for your team):
+
+- **[API keys](/agenteye/api-keys)**: scoped tokens for the collector, the dashboard, and the assistant.
+- **Users**: passwordless, email-based sign-in with an allowlist.
+- **Settings**: per-org configuration, including model context-window overrides.
+
+---
+
+## How the pieces fit
+
+Data flows in one direction, from your agent code to the dashboard: your agent (via the Python SDK) emits events to the agenteye-collector, which ships them to the server, which serves the dashboard. Two optional services round it out — a scoring service (evaluations) and an AI assistant service (the in-dashboard chat).
+
+- **Python SDK**: you add a few `agenteye.event.*` calls to your agent; events are buffered locally.
+- **agenteye-collector**: a lightweight daemon on each agent machine that batches events and ships them to the server.
+- **Server**: ingests your events, keeps operational state in your own databases, and serves the REST API that the dashboard, CLI, and your own integrations all use.
+- **Dashboard**: where you explore everything.
+- **Optional services**: a scoring service (evaluations), and an AI assistant service (the in-dashboard chat).
+
+For the vocabulary used throughout the docs (*event, session, evaluation, audit, finding, incident*), see [Concepts](/agenteye/concepts).
+
+---
+
+## Getting Failproof AI Observability
+
+Failproof AI Observability is an enterprise product from Failproof AI, and it works alongside Failproof AI Enforcement — the policy and guardrail product — under the Failproof AI brand. It runs entirely in your own environment. If you don't have access to the packages yet, request a demo and we'll get you set up: email [nikita@befailproof.ai](mailto:nikita@befailproof.ai).
+
+---
+
+## Next steps
+
+- [Concepts](/agenteye/concepts): the Failproof AI Observability vocabulary in one place.
+- [Observability](/agenteye/observability): follow what your agents do, run by run.
+- [Security](/agenteye/security): how Failproof AI Observability keeps your data isolated and in your control.

package/.next/standalone/docs-old/agenteye/python-sdk-skill.mdx

@@ -0,0 +1,131 @@
+---
+title: "Failproof AI Observability Python SDK Agent Skill"
+description: "Go from an uninstrumented agent to events you can see, with your coding agent finding the instrumentation points, writing them, and proving they landed."
+---
+
+Tell your coding agent *"add Failproof AI Observability to this agent"* and let it read your loop, work out where the instrumentation belongs, write it, and verify the events before it calls the job done.
+
+The **Python SDK skill** (`agenteye-python-sdk`) is an *Agent Skill*: a folder of instructions that a coding agent such as Claude Code or Codex loads on demand when a task matches it. It teaches the agent to use the [Python SDK](/agenteye/python-sdk) — it is not a library, and it changes nothing about how the SDK works.
+
+## Instrumentation is easy to write and easy to get quietly wrong
+
+The SDK is small: thirteen event methods, all keyword-only. A coding agent can read the [Python SDK](/agenteye/python-sdk) reference and produce plausible instrumentation in a minute.
+
+The catch is that this SDK does not raise when you get it wrong, and wrong instrumentation looks exactly like right instrumentation until someone opens a dashboard and finds it empty. The mistakes that cost real time are all silences:
+
+| The mistake | What you see |
+|---|---|
+| No `agent_start` | Every event lands. Zero sessions. |
+| Environment never set | Everything works, filed under `dev`. |
+| `outcome="failure"` | The run shows green — only `failed`, `error`, `timeout`, `rejected` count. |
+| A typo'd field name | Accepted and stored as a new field. |
+| Events emitted from a thread pool | Silently dropped. |
+
+None of these raise. None show up in tests. Every one is in the skill, stated as a contract with the check that catches it.
+
+## What it does, in order
+
+The skill runs the same three steps a careful engineer would:
+
+1. **Plan.** It reads your agent loop and asks the two questions only you can answer: what counts as one run (your `session_id`), and who the distinguishable actors are (your `agent_id`). It gets those agreed before writing code, because changing them later splits your history and breaks the trends.
+2. **Write.** It binds identity once per run rather than threading it through every call site, and it picks a concurrency-safe shape — a detail that matters, because the obvious shortcut silently mixes two overlapping runs into one session.
+3. **Verify.** It runs your agent and reads the resulting event files, checking that `agent_start` is present, the environment is right, and one run produced one session.
+
+That third step is the one people skip. The SDK writes events to local files, so a complete integration can be proven on a laptop with no server, no API key, and no network — which is exactly why the skill insists on doing it.
+
+## How it relates to the other skills
+
+Three skills, one clean split:
+
+| Skill | Reach for it when | What it touches |
+|---|---|---|
+| **Python SDK skill** (this page) | You want your agent to *emit* telemetry — "add observability", "why isn't my agent showing up?" | Writes code in your agent's repo. Reads nothing. |
+| **[Evaluator skill](/agenteye/evaluator-skill)** | You want to *score* runs — "what should we even measure?" | Writes code in your repo; reads telemetry |
+| **[CLI skill](/agenteye/cli-skill)** | You want to *read* what happened, or operate your deployment | Drives the CLI as you, including changes |
+
+They hand off in that order: this skill gets events flowing, the evaluator scores them, the CLI reads them back. There is nothing to evaluate and nothing to read until your agent emits sessions, so if you are starting from scratch, start here.
+
+## Prerequisites
+
+1. **Python 3.10+** and the agent codebase you want to instrument.
+2. **The SDK.** It is distributed to customers as a private wheel rather than from a public index — your onboarding covers how to get it and install it. The skill knows the install path and will ask you rather than guess if it cannot find it.
+3. **Nothing else.** No dashboard login, no API key, no network. The skill verifies against the event files the SDK writes, so it can finish and prove its work offline.
+
+## Where to get it
+
+The skill lives in the public [`FailproofAI/skills`](https://github.com/FailproofAI/skills) collection:
+
+```bash
+npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code
+```
+
+Add `-g` to install it for every project instead of just the current one, and `--copy` if your environment does not follow symlinks. For Codex, pass `-a codex`.
+
+## Installing it by hand
+
+Agent Skills are folders containing a `SKILL.md` plus references. If you would rather not use the installer:
+
+- **Claude Code**: copy the `agenteye-python-sdk/` folder into `~/.claude/skills/` (every project) or `<your-repo>/.claude/skills/` (that repo only). Claude Code discovers it automatically — check the `/skills` list, or just ask something that matches it.
+- **Codex**: Codex reads the same `SKILL.md`. The bundled `agents/openai.yaml` sets `allow_implicit_invocation: true`, so it is auto-selected when a task matches; otherwise invoke it as `$agenteye-python-sdk`.
+
+Run your agent **in the repository holding the code you want instrumented** — the skill reads your agent loop before it proposes anything.
+
+## What a session looks like
+
+```text
+you   ▸ Add Failproof AI Observability to this agent.
+
+agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic
+        wrapper in llm.py. Two questions before I write anything.
+
+        What counts as one run? You handle requests concurrently, so I'd
+        use the request id you already have in ctx.request_id — then a
+        session here and a request in your logs are the same string.
+
+        And who are the actors? I see a planner path and a researcher
+        path. Label them separately, or is that one agent to you?
+
+you   ▸ Request id is right. They're one agent, call it "assistant".
+
+agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and
+        agent_end bracket handle_request, including the error path. Used
+        a context-local for identity — your dispatcher runs tools in a
+        thread pool, and the simpler approach would have mixed concurrent
+        runs into one session without complaining.
+
+        Verified against a real run: 11 events across 4 files —
+        agent_start, model_request/response, tool_use/tool_result x3,
+        agent_end (outcome=success). environment=production, one session
+        per request, durations paired.
+
+        One thing I did NOT do: your worker pool in batch.py submits
+        straight to the executor, so events from there would be dropped.
+        Want me to fix those too?
+```
+
+The pattern to notice: it read the code before proposing, asked only the questions you can answer, reused an id you already had, chose the concurrency-safe shape *because* it saw a thread pool, and **verified by reading the actual events** rather than declaring success — then flagged the one place it knew would fail quietly.
+
+## What you can ask it
+
+- *"Why isn't my agent showing up on the dashboard?"* → walks the ladder: are events being written, is `agent_start` there, is the environment right, is the collector reading the same place.
+- *"Everything's landing under dev."* → the environment was never set, or was reset by a later call.
+- *"Add token tracking."* → finds your LLM wrapper and records model, stop reason, and usage.
+- *"Instrument the sub-agents too."* → one session, distinct agent labels, nested under their parent.
+- *"Write tests for the instrumentation."* → points the SDK at a temporary directory and asserts on the events it wrote.
+
+## What to watch for
+
+**Let it verify.** The step that makes this skill worth using is the last one — running your agent and reading the events back. An agent that writes instrumentation and stops has done the easy half, and the half that fails silently is the other one.
+
+**Agree the names before the code.** `session_id` and `agent_id` are the axes every surface groups by. Renaming them later splits the history: old runs keep the old labels and your trends break. The skill will ask; the answer is worth a minute's thought.
+
+**If your agent proposes installing the SDK from a public index, the skill did not load.** The SDK is distributed privately. That proposal is a reliable tell that your coding agent is guessing rather than following the skill — stop it there and check the skill is installed.
+
+Beyond that its blast radius is small: it writes code in your working directory and event files where you tell it. It reads nothing from your deployment and changes nothing about it.
+
+## Next steps
+
+- **[Python SDK](/agenteye/python-sdk)**: the complete event reference — every event type and field — behind what this skill automates.
+- **[Sessions](/agenteye/sessions)**: what your instrumentation produces once events land.
+- **[Evaluator Agent Skill](/agenteye/evaluator-skill)**: the next step once runs are landing — scoring them.
+- **[CLI Agent Skill](/agenteye/cli-skill)**: reading your telemetry back.