# Assay — agent door (load this first)

> Local ledger for AI work. Records priced usage spans and sealed transcript turns on a store you own. Not in the request path.

**Point an agent at this file:** https://docs.assay.solutions/llms.txt

Public site: https://docs.assay.solutions
Human page: https://docs.assay.solutions/agents
Machine index: https://docs.assay.solutions/catalog.json
CLI verbs: https://docs.assay.solutions/commands.json

Product: assay 0.48.0. macOS collector (invite install) or Node ≥ 20 library.

This is the **user guide**. It is not a map of the source tree.

## How to traverse (progressive disclosure)

Do **not** read the whole site.

1. Load **this file**. It is the table of contents.
2. Match the human's ask to **one group**, then **one or two pages**.
3. Fetch the **`.md` URL** (markdown, no chrome). HTML is for people.
4. Stop when the page answers the ask. Follow a related link only if the task still has a hole.
5. For a command, flags, or `--yes` rules, load `commands.json` instead of guessing.

Each page is self-contained. Summaries below are enough to choose. Open the page for the how.

## Golden rules

1. Prefer `--json` when you will parse.
2. Inspection verbs do not create a database. `init` / `capture` / `serve` / `seed` write.
3. `assay shred` is irreversible and requires `--yes`. Do not shred unless the human asked.
4. Do not put tokens, API keys, or the content key on argv.
5. Do not bind the dashboard on a public interface. Loopback is the boundary.
6. Do not mint a share unless the human asked to publish **this** sitting. Read the page before leaving it up.
7. Do not run a remote full-content judge unless the human opted in on that command.
8. `assay pricing watch` is the only CLI verb that reaches the network. It does not open the store.

## First commands

```
assay --version
assay show --json
assay capture claude-code
assay dashboard
assay turns --session <id> --json
```

## Table of contents

Markdown: `https://docs.assay.solutions/<id>.md`
HTML: `https://docs.assay.solutions/<id>`

### Get started

- [Start here](https://docs.assay.solutions/index.md) — What Assay is, the three records it joins, two applications.
- [Install](https://docs.assay.solutions/install.md) — Invite installer, `assay init`, back up the content key.
- [After install](https://docs.assay.solutions/first-run.md) — Capture, dashboard, sweep, labelling: the standing loop.
- [Applications](https://docs.assay.solutions/applications.md) — Your own AI work (corpus) vs observability in an agent loop.

### How it works

- [How it works](https://docs.assay.solutions/how-it-works.md) — Capture → price → seal → overlay → read.
- [What is recorded](https://docs.assay.solutions/data.md) — Spans, turns, sittings, overlays, and how they join.
- [Framing](https://docs.assay.solutions/framing.md) — Product, objective, goal, episode, touch, type, scope. What takes money.
- [Honesty](https://docs.assay.solutions/honesty.md) — Unknown is not zero. Corrections. Two named readings.
- [Privacy and keys](https://docs.assay.solutions/privacy.md) — Sealed text, shred, loopback, what may leave the machine.

### Capture and labels

- [Capture](https://docs.assay.solutions/capture.md) — Sweep harness logs (Claude Code, Grok, Codex, OpenCode) and the timer.
- [Labelling](https://docs.assay.solutions/labelling.md) — Place sittings using the AI they already pay for. Two switches.
- [Agent loop](https://docs.assay.solutions/agent-loop.md) — `record` / `recordTurn` / `declareSession` from your own product.
- [Debug console](https://docs.assay.solutions/debug.md) — `assay turns`: decrypted timeline with cost. Scriptable.
- [Ingest](https://docs.assay.solutions/ingest.md) — OTLP/HTTP door for `gen_ai` traces.

### The console

- [Dashboard](https://docs.assay.solutions/dashboard.md) — Read-only local console. Loopback is the boundary. Snapshot.
- [Sessions](https://docs.assay.solutions/sessions.md) — Sitting list, timeline, type writer, folds.
- [Products](https://docs.assay.solutions/products.md) — Tree product vs path product. Inclusive and weighted.
- [Objectives](https://docs.assay.solutions/objectives.md) — Tree, episodes, touches, unplaced, proposed nodes.
- [Type](https://docs.assay.solutions/type.md) — Kind of work. Closed vocabulary. Not the objective tree.
- [Spend, waste, and ROI](https://docs.assay.solutions/spend.md) — Token phases, waste detectors, ROI that names exclusions.
- [Search](https://docs.assay.solutions/search.md) — On-machine search of what was said. `exact` outranks `related`.
- [Share](https://docs.assay.solutions/share.md) — Mint one sitting as a flat page. Unpublish, delete, agent bundle.
- [Embed](https://docs.assay.solutions/embed.md) — `<assay-dashboard>` behind the host's login.

### Reference

- [CLI reference](https://docs.assay.solutions/cli.md) — Every verb, grouped by task.
- [Config](https://docs.assay.solutions/config.md) — File resolution, products, labelling, mode.
- [Pricing](https://docs.assay.solutions/pricing.md) — Check, watch, reprice, local overlay. Unknown is not $0.
- [For agents](https://docs.assay.solutions/agents.md) — Operating procedure (this audience).
- [Troubleshooting](https://docs.assay.solutions/troubleshooting.md) — Empty store, keys, labelling refused, binds, shares.

## Which page for a common ask

| The human says | Open |
|---|---|
| Install / get started | install.md then first-run.md |
| How does Assay work | how-it-works.md then data.md |
| What do the words mean / what takes money | framing.md |
| Capture my coding sessions | capture.md |
| Label sittings / unplaced | labelling.md |
| Put Assay in our agent | agent-loop.md then debug.md |
| Open the console | dashboard.md |
| What did this product cost | products.md |
| Share a session with someone | share.md |
| Search what was said | search.md |
| A command or flag | commands.json then cli.md |
| Dashboard will not bind / unreadable turns | troubleshooting.md |