# 9 · Reference

> Quick lookups for everything the journey covered. Live, exhaustive docs ship inside the CLI: `rote guidance [topic]`, `rote grammar [topic]`, `rote man <topic>`, `rote how`.

## Install & identity

```bash
curl -fsSL https://getrote.dev/install | bash
rote login                    # browser-based sign-in
rote whoami                   # ok: you@example.com
rote pull powerpack --yes     # optional: curated adapters + plays in one command
```

## Running plays

```bash
rote play run <target> [key=value …]        # target: URI | org/name[@ver] | local name | path
rote play run <target> … --output=summary   # one line
rote play run <target> … --output=json      # canonical structured result
rote play run <target> … -y/--yes           # skip confirm prompts (CI / non-TTY)
rote play run <target> … --resume <run_id>  # continue a failed/interrupted run
rote play run <target> … --max-concurrency <N>
rote play run <target> … --dry-run
```

**URI forms**

```
https://play.modiqo.ai/<owner>/<name>            # floats to latest release
https://play.modiqo.ai/<owner>/<name>@1.2.3      # pinned, immutable
https://play.modiqo.ai/install?play=<owner>/<name>@1.2.3    # bootstrap/install URI
```

## Finding & vetting

```bash
rote play search "<query>"                  # local + registry
rote play inspect <uri> [--json]            # the play card: params, ACCESS block, version
rote explore "<intent>"                     # cross-adapter capability discovery
rote play run https://play.modiqo.ai/modiqo/play-dag play=<uri-or-path>   # x-ray any DAG
```

## Workspace (explore → crystallize)

```bash
rote init <name> --seq                      # open a workspace (flight recorder)
rote proc run <program> [args…]             # shell reach — capture as @N
rote browse <url>                           # browser reach — navigate → wait → snapshot → slice
rote query @N '<jq>' -r                     # read a field by reference
rote query schema @N                        # inspect a response's shape
rote query @N '<jq>' -s <var>               # save a scalar as $var
rote play pending write <ws> --name … --description …   # anchor reusable work
rote play pending list | show <ws> | discard <ws>
rote workspace export <ws> [--params <NAMES>] [-f shell|steps|typescript] [--with-presentation]
```

## Authoring & publishing

```bash
rote play lint <main.ts>                    # contract checks; fix what it names
rote play release <org/name> [--force] [--keep-local]
rote registry play push <play-path> <slug> [--private] [--dry-run] [--allow-undeclared-endpoints]
rote registry play pull <org/name> [--yes] [--no-deps]
rote registry play visibility <org/name> <public|private>
rote registry play list | search <q> | info <org/name> | delete | restore
rote play share create --audience <organization|users> [--user <handle>] [--expires-in <dur>]
```

**The chain:** lint → test (happy + negative) → release → push → **canonical readback** (run the published URI). Versions are immutable; every change is a bump.

## Adapters (API reach)

```bash
rote adapter new <id> [spec]                # from OpenAPI / Discovery / GraphQL / gRPC / catalog
<id>_probe   "<intent>"                     # semantic search over the API's operations
<id>_call    <method> key=value …           # execute one
<id>_batch_call                             # parallel batch
rote registry play find-by-adapter <adapter-id>
```

## Step grammar cheat sheet

```yaml
steps:
  my_step:
    type: process.exec                      # or adapter/<id>, adapter.auth.ensure,
    timeout_ms: 30000                       #    browser.navigate|wait|extract|click|type
    depends_on: [other_step]                # ordering edge (barrier)
    for_each: '$.items'                     # fan out per item → $item, $item_index
    max_concurrency: 4
    argv:
    - python3
    - -c
    - |2

      …script; stdout is data, exit status is the failure signal…
    - $my_param                             # play parameter
    - '@other_step{$.stdout.text | fromjson | .field}'   # value edge (must be scalar)
```

**Rules that bite:**

- Value-edge jq must resolve to a **scalar**; the dialect has `fromjson`, field access, `join`, `map/select`, `to_entries` — no `tojson`. Pack collections into a delimited scalar field (`chr(31)`/`chr(30)` separators) and unpack in the consumer.
- No literal `*/` anywhere inside the frontmatter comment.
- `parameters:` use `param_type`; quote non-string defaults (`default: '20'`).
- Steps have **no TTY** — pass `--yes`-style flags to any subcommand that might prompt.
- Presentation: `stepName("literal")` only; call all three of `out.human` / `out.summary` / `out.result`; `out.result` takes an object literal.

## The failure model

| Situation | Step behavior | User sees |
|---|---|---|
| Expected absence (endpoint down, feature off, none found) | `{"ok":true,"warning":"…"}`, exit 0 | `degraded`/`skipped` ledger row, play completes |
| Hard fault (bad input, missing required tool) | message → stderr, exit ≠ 0 | step `FAILED`, dependents `BLOCKED`, `--resume` offered |
| Destructive work | own step, gated by `apply=true` | dry-run by default, labeled `skipped` stage |

## Representation parity

`human`, `summary`, `json` are views of one run. No semantic fact may silently disappear from a view that claims completeness. Truncate only with a declared count; make `out.result` the canonical superset; declare it:

```ts
representations: {
  human:   "complete — …",
  json:    "canonical — …",
  summary: "intentionally lossy — …",
}
```

Compare views from the **same run** when testing (`--resume <run_id> --output=json` re-renders recorded outcomes).

## Troubleshooting

| Symptom | Likely cause → fix |
|---|---|
| `interactive prompt required but stdin is not a terminal` | confirm prompt in non-TTY → add `--yes` |
| `must resolve to scalar values` | value edge returns object/array → pipe to a field / `join(",")` / packed scalar |
| `JSONPath '…' returned no results` | unsupported jq filter (e.g. `tojson`) or wrong path → `rote query schema @N` during exploration |
| `frontmatter is closed early by a */` | literal `*/` inside the JSDoc frontmatter → remove/reword it |
| `data did not match any variant of untagged enum ParameterFormat` | unquoted non-string default → `default: '20'` |
| push rejected: visibility mismatch | play record is private, push assumed public → `--private` or flip with `registry play visibility` |
| push rejected: undeclared endpoints | steps call an adapter missing from `requires_endpoints` → declare it (escape hatch: `--allow-undeclared-endpoints`) |
| `FLOW_OUTPUT_BARE_CONSOLE_LOG` | `console.log` in a step/presentation → `process.stdout.write(JSON.stringify(x) + "\n")` |
| run failed midway | fix the cause, then `rote play run … --resume <run_id>` — completed steps restore |

## Exemplars to copy from

| Play | Why it's worth reading |
|---|---|
| `modiqo/hello` | 9 steps · 2 layers; self-probing roots, value-edge fan-out, glyph stage ledger |
| `modiqo/play-dag` | 4 steps · 3 layers; identity-gated URI pull; representation-parity contract |
| `modiqo/dns-propagation-check` | the canonical validate → parallel probes → verdict-join shape |
| `modiqo/dependency-vulnerability-check` | 10 steps · 5 layers; per-ecosystem fan-out, staged resume points |
| `modiqo/cleanup-merged-git-branches` | destructive work done right: gated `apply=true` deletion stage |