# Plays — developer documentation

> *"Skills tell the agent how to think; **plays are what worked, ready to run again**."*

A **play** is a saved, runnable unit of work: someone did a task once — carefully, on the record — and crystallized it into a typed, versioned artifact that lives at a URI anyone can inspect and run. Plays are the center of gravity of this product. Everything else — workspaces, adapters, the browser, the DAG runner — exists to make plays plentiful, trustworthy, and yours to create.

![The journey](assets/journey.svg)

## How to read these docs

Each section leaves you *productive* before the next one starts. Run something real in five minutes; make plays a daily habit; create your own; and go deep on the machinery only when you actually need it. Skipping ahead is fine — every section says where you are and what it assumes.

| § | Read it when… | You leave able to… |
|---|---|---|
| [1 · Run your first play](01-run-your-first-play.md) | you have 5 minutes and a terminal | run any play from a URI, read its report, pass parameters |
| [2 · Work with plays](02-work-with-plays.md) | you want plays in your daily work | search, inspect play cards, pin versions, share, control visibility |
| [3 · Create your first play](03-create-your-first-play.md) | your search came up empty | explore in a workspace and **crystallize** the trace into a published play |
| [4 · How the play travels](04-how-the-play-travels.md) | the method needs to leave your machine | push, list, inspect, pull, and preserve ownership, privacy, dependencies, and lineage |
| [5 · What Plays make possible](05-what-plays-make-possible.md) | you want the strategic and AI-system use cases | use Plays for recall, expertise transfer, composition, evals, and trajectory learning |
| [6 · Anatomy of a play](06-anatomy-of-a-play.md) | lint complains, or you're curious | read/write frontmatter, steps, edges, presentations, deps — fluently |
| [7 · Modalities](07-modalities.md) | your task lives beyond the shell | reach APIs (adapters), processes (shell), and the web (browser) — and route between them |
| [8 · Workspace & CAUs](08-workspace-and-caus.md) | you want to know *why* it works | explain CAUs, the canvas, and why a trace of references is already a DAG |
| [9 · Reference](09-reference.md) | you know what you need | look up any command, rule, or error in seconds |

## The product in four sentences

1. **Explore** with three kinds of reach — APIs, shell, browser — inside a **workspace** that records every call as a **Context Addressable Unit** (`@1`, `@2`, `@3`): persistent, queryable artifacts, not logs.
2. Because you hold *references* instead of pasted payloads, your trace **is a dataflow graph** — the record of what happened is, by construction, a program that can happen again.
3. **Crystallization** compiles that trace (Filter → Reify → Resolve → Fingerprint → Generate) into a **play**: a declared step DAG the runner can parallelize, resume, and audit, plus an honest report.
4. **Share** it: one push, one immutable version, one URI — `https://play.modiqo.ai/you/your-play` — inspectable by anyone, runnable by everyone you allow.

## Fastest possible start

```bash
curl -fsSL https://getrote.dev/install | bash
rote login
rote play run https://play.modiqo.ai/modiqo/dns-propagation-check domain=yourdomain.com
```

Then start at [§1](01-run-your-first-play.md).

---

*These docs cover the play-centric developer path. The CLI carries its own exhaustive live documentation — `rote guidance`, `rote grammar`, `rote man` — which these pages link into rather than duplicate.*