@junoflow/cli 0.3.0 → 0.9.0

package/README.md

@@ -1,52 +1,691 @@
 # @junoflow/cli
 
-Develop [Juno](https://github.com/boivie/juno) integrations locally: scaffold a
-project, generate types from your manifest, check it, and deploy it.
+Develop [Juno](https://github.com/boivie/juno) flows and integrations, and
+operate a Juno instance, from the command line.
 
 ```bash
-npm install --save-dev @junoflow/cli
-npx juno init my-integration --url http://juno.local:8080
+npm install --save-dev @junoflow/cli     # in a flow or integration working copy
+npm install --global @junoflow/cli       # to operate an instance from anywhere
 ```
 
+The package installs one command, `juno`, with two sets of commands:
+
+- **Operating an instance**: `juno <group> <verb> [id]` puts a named command in
+  front of every tool Juno's in-app assistant uses, so a coding agent (Claude
+  Code and similar), a shell script or a person can find things and act on them.
+  `juno ask` talks to the assistant itself.
+- **Working copies**: `juno flow init`, `juno integration init` and the commands
+  beside them write a flow or an integration to disk as files, check it, and
+  deploy it. See [Working copies](#working-copies).
+
+Juno has **no authentication on any endpoint**. An instance is a trusted-LAN
+appliance; do not expose one to the internet.
+
+## Operating an instance
+
+```bash
+juno config set url juno.local:8080          # once, outside a project
+juno discover porch --kind state
+juno state get porch-dark --jq .value
+juno related endpoint:ha:light.hallway --degree 2
+juno state preview-layers porch-dark --input - <<'EOF'
+{"ops":[{"op":"insert", …}]}
+EOF
+juno ha call-service --input '{"domain":"light","service":"turn_off"}'
+```
+
+The grammar is `juno <group> <verb> [id]`. The group is the kind of thing a
+command acts on, so a `discover` hit's `{kind, id}` leads straight to
+`juno <kind> <verb> <id>` and `juno related <kind>:<id>` (or `<kind> <id>`). A
+verb may also be spelled with `_` (`juno state get_history`).
+
+Every tool command sends the tool's own JSON input, and prints the tool's JSON
+answer. The CLI holds no tool semantics: the instance validates the input,
+writes the descriptions and classifies each command's effect.
+
+### Help
+
+| Command                      | Shows                                                                                                                       |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `juno --help`                | the groups and top-level commands. Offline.                                                                                 |
+| `juno <group> --help`        | the group's commands, each with its effect and the first sentence of its description. Offline, it lists the commands alone. |
+| `juno <group> <verb> --help` | the tool's full description, its effect, its input schema, and what the positional and flags fill in. Needs the instance.   |
+
+`juno <group>` on its own prints the group's help and exits 2. An unknown
+command suggests the closest one: `juno stat get` answers
+`did you mean "juno state get"?`.
+
+### Effects
+
+Every command has one effect:
+
+- **read** changes nothing.
+- **change** writes stored configuration that keeps a version timeline, so it
+  can be reverted.
+- **act** does something now (calls a service, presses a button, sets a value,
+  starts a run, executes code), with nothing to roll back to.
+
+`config set` and `agent-skill install` are **local**: they write a file on your
+machine and change nothing on the instance. So is `app dev`, which serves an app
+working copy on localhost and never connects to an instance.
+
+No command of a lower effect is a string prefix of a command of a higher one.
+Claude Code matches a Bash permission rule by prefix, so an allowlist can list
+the read commands, and optionally the change commands, and every act still
+prompts.
+
+### Commands
+
+The positional fills the named input field. A dash means the command takes no
+positional; its input is a whole document (`device write`) or has no id
+(`run list`).
+
+**Top level**
+
+| Command                                 | Tool          | Positional                          | Effect |
+| --------------------------------------- | ------------- | ----------------------------------- | ------ |
+| `juno discover <query> [--kind k]…`     | `discover`    | `query`; `--kind` → `kinds`         | read   |
+| `juno related <kind>:<id> [--degree n]` | `get_related` | `kind`, `id`; `--degree` → `degree` | read   |
+| `juno skill [<name>] [--json]`          | none          | skill name                          | read   |
+| `juno ask ["<prompt>"]`                 | none          | the prompt                          | act    |
+| `juno agent-skill install`              | none          | none                                | local  |
+
+`related` splits its positional on the first `:` only, so
+`endpoint:ha:light.hallway` is kind `endpoint`, id `ha:light.hallway`.
+
+**`state`**
+
+| Command                     | Tool                                  | Positional | Effect |
+| --------------------------- | ------------------------------------- | ---------- | ------ |
+| `juno state get`            | `get_state`                           | `id`       | read   |
+| `juno state get-history`    | `get_state_history`                   | `id`       | read   |
+| `juno state get-layers`     | `get_state_layers`                    | `id`       | read   |
+| `juno state evaluate-level` | `evaluate_level`                      | —          | read   |
+| `juno state preview-layers` | `edit_state_layers`, `dry_run: true`  | `id`       | read   |
+| `juno state create`         | `create_state`                        | `id`       | change |
+| `juno state edit-layers`    | `edit_state_layers`, `dry_run: false` | `id`       | change |
+| `juno state set-value`      | `set_state_value`                     | `id`       | act    |
+| `juno state claim`          | `claim_state`                         | `id`       | act    |
+| `juno state release`        | `release_state`                       | `id`       | act    |
+
+`preview-layers` and `edit-layers` call the same tool. The preview always sends
+`dry_run: true`, so a permission rule can allow the preview and not the edit; an
+`--input` that says `"dry_run": false` is refused.
+
+**`flow`**
+
+| Command                  | Tool               | Positional | Effect |
+| ------------------------ | ------------------ | ---------- | ------ |
+| `juno flow get`          | `get_flow`         | `id`       | read   |
+| `juno flow set-enabled`  | `set_flow_enabled` | `flow_id`  | change |
+| `juno flow trigger`      | `trigger_flow`     | `flow_id`  | act    |
+| `juno flow fire-trigger` | `fire_trigger`     | `flow_id`  | act    |
+
+The group's working-copy commands (`flow init`, `gen-types`, `check`, `deploy`,
+`pull`) are in [Flows as files](#flows-as-files).
+
+**`run`**
+
+| Command         | Tool        | Positional | Effect |
+| --------------- | ----------- | ---------- | ------ |
+| `juno run list` | `list_runs` | —          | read   |
+| `juno run get`  | `get_run`   | `run_id`   | read   |
+
+**`integration`**
+
+| Command                         | Tool                       | Positional    | Effect |
+| ------------------------------- | -------------------------- | ------------- | ------ |
+| `juno integration get`          | `get_integration`          | `id`          | read   |
+| `juno integration configure`    | `configure_integration`    | `id`          | change |
+| `juno integration install`      | `install_integration`      | —             | act    |
+| `juno integration run-schedule` | `run_integration_schedule` | `integration` | act    |
+
+The group's working-copy commands (`integration init`, `gen-types`,
+`verify-types`, `check`, `deploy`, `pull`) are in
+[Developing integrations](#developing-integrations).
+
+**`device`**
+
+| Command               | Tool             | Positional | Effect |
+| --------------------- | ---------------- | ---------- | ------ |
+| `juno device list`    | `list_devices`   | —          | read   |
+| `juno device get`     | `get_device`     | `id`       | read   |
+| `juno device preview` | `preview_device` | —          | read   |
+| `juno device write`   | `write_device`   | —          | change |
+| `juno device suspend` | `suspend_device` | `id`       | act    |
+| `juno device release` | `release_device` | `id`       | act    |
+
+**`control`**
+
+| Command                | Tool              | Positional | Effect |
+| ---------------------- | ----------------- | ---------- | ------ |
+| `juno control write`   | `write_control`   | —          | change |
+| `juno control use`     | `use_control`     | `id`       | act    |
+| `juno control release` | `release_control` | `id`       | act    |
+
+**`finding`**
+
+| Command            | Tool          | Positional | Effect |
+| ------------------ | ------------- | ---------- | ------ |
+| `juno finding get` | `get_finding` | `slug`     | read   |
+
+**`webhook`**
+
+| Command                       | Tool                     | Positional | Effect |
+| ----------------------------- | ------------------------ | ---------- | ------ |
+| `juno webhook list`           | `list_webhooks`          | —          | read   |
+| `juno webhook get-deliveries` | `get_webhook_deliveries` | `id`       | read   |
+| `juno webhook write`          | `write_webhook`          | `id`       | change |
+| `juno webhook fire`           | `fire_webhook`           | `id`       | act    |
+
+**`credential`**
+
+| Command                    | Tool               | Positional    | Effect |
+| -------------------------- | ------------------ | ------------- | ------ |
+| `juno credential list`     | `list_credentials` | —             | read   |
+| `juno credential set <id>` | none               | credential id | act    |
+
+**`ha`** (Home Assistant)
+
+| Command                      | Tool                 | Positional  | Effect |
+| ---------------------------- | -------------------- | ----------- | ------ |
+| `juno ha get-entity`         | `get_entity`         | `entity_id` | read   |
+| `juno ha get-entity-history` | `get_entity_history` | `entity_id` | read   |
+| `juno ha list-services`      | `list_services`      | —           | read   |
+| `juno ha call-service`       | `call_service`       | —           | act    |
+
+**`script`**
+
+| Command                               | Tool         | Positional                                            | Effect |
+| ------------------------------------- | ------------ | ----------------------------------------------------- | ------ |
+| `juno script run <file> [--cred id]…` | `run_script` | `<file>` → `files`, `entry`; `--cred` → `credentials` | act    |
+
+`script run` reads the file relative to the working directory, puts its content
+under `files` by its basename and makes it the `entry`.
+
+**`session`** and **`config`**
+
+| Command                     | Tool | Positional  | Effect |
+| --------------------------- | ---- | ----------- | ------ |
+| `juno session approve <id>` | none | session id  | act    |
+| `juno config set url <url>` | none | `url <url>` | local  |
+
+There is no command that calls a tool by name. One permission rule for such a
+command would allow every act, so each tool has its own command instead, and a
+tool added to the server needs a CLI release to reach.
+
+### Input
+
+The id, when the command has one, is the single positional argument. Everything
+else is the tool's input JSON, given with `--input`:
+
+| Form               | Reads                                     |
+| ------------------ | ----------------------------------------- |
+| `--input '<json>'` | the JSON itself                           |
+| `--input -`        | standard input                            |
+| `--input @<path>`  | a file, relative to the working directory |
+
+The input must be a JSON object. Without `--input` it is `{}`. The CLI never
+reads standard input unless `--input -` asks for it, because an open, empty
+stdin would hang an agent, and it never prompts off a terminal.
+
+The input is built in this order: the `--input` object, then the positional into
+its field, then the command's flags, then the fixed input (`preview-layers`'
+`dry_run`). A positional or flag that disagrees with a value already in
+`--input` is a usage error naming both. The CLI checks nothing else: the
+instance validates the input against the tool's schema and answers with the
+failing field (`/id`, `/ops/0/when`, `/` for the input as a whole).
+
+### Output
+
+Standard output carries the tool's answer and nothing else:
+
+- off a terminal, the instance's JSON byte for byte;
+- on a terminal, the same JSON indented by two spaces. Never coloured.
+
+The choice follows whether stdout is a terminal, so a script and an agent see
+the same bytes. A tool that fails in its own terms answers `{"error": "…"}`;
+that is printed on stdout like any answer, and the exit code is 1. Warnings,
+progress and notes go to standard error.
+
+`--jq <expr>` runs the answer through [`jq`](https://jqlang.org), which must be
+on `PATH` (`jq -c` off a terminal, plain `jq` on one). A filter given this way
+stays inside the command's own permission rule, where a pipe to `jq` would need
+its own. A missing `jq` or an expression `jq` rejects exits 2.
+
+### Exit codes
+
+One table for the whole CLI, the working-copy commands included:
+
+| Code | When                                                                                                 |
+| ---- | ---------------------------------------------------------------------------------------------------- |
+| 0    | Success                                                                                              |
+| 1    | A tool answer with a top-level string `error`, a failed check or deploy, or any other failure        |
+| 2    | Usage: an unknown command or flag, bad `--input`, input the instance rejects, a bad `--jq`           |
+| 3    | The instance is unreachable                                                                          |
+| 4    | A working-copy `deploy` or `check`, any kind: the instance changed since the working copy was pulled |
+| 5    | `juno ask` / `session approve`: the turn is still running                                            |
+| 6    | `juno ask` / `session approve`: the assistant is waiting for an answer or an approval                |
+
+An instance that does not serve a tool the CLI names is older than the CLI; that
+is also exit 2, and the message says so.
+
+### `juno ask` and `juno session approve`
+
+`juno ask` sends a prompt to Juno's in-app assistant through the
+[Agent Prompt API](https://boivie.github.io/juno/reference/agent-api/) and
+prints the turn's final event. It is for scripts, chat bridges and a person at a
+terminal. Its effect is **act**, because the assistant can do anything its tools
+allow.
+
+```bash
+juno ask "Why is the porch lamp on?"
+juno ask --session <id> "And the hallway?"     # continue a conversation
+juno ask --session <id>                        # keep waiting on a running turn
+juno session approve <id>                      # let a pending tool call through
+juno ask --session <id> "not while I'm away"   # deny it, with a reason
+```
+
+| Option             | Meaning                                                                          |
+| ------------------ | -------------------------------------------------------------------------------- |
+| `--session <id>`   | resume that session. With no prompt, observe it: wait for its turn, send nothing |
+| `--wait <seconds>` | off a terminal, how long one call waits before answering pending (default 60)    |
+
+Off a terminal each call is one request that waits up to `--wait` seconds, and
+the final event is printed unchanged. On a terminal the answer streams: progress
+and the session id go to standard error, and the final event is printed
+indented. The exit code is the outcome:
+
+| Event                                           | Exit |
+| ----------------------------------------------- | ---- |
+| `message`, or `done` with `completed`           | 0    |
+| `pending` (still running)                       | 5    |
+| `awaiting_input` (question or approval)         | 6    |
+| `done` with `failed` or `abandoned`, or `error` | 1    |
+
+So "keep waiting" is `juno ask --session <id>` until the exit code is not 5. A
+new conversation's session id is minted by the CLI, so a retry after a dropped
+connection resumes the same session; a failed connection is retried twice before
+exit 3. When the session is busy with another turn, `juno ask` waits for that
+turn to end and sends again (up to three times), unless the turn ends waiting
+for input, since the message would then be taken as the answer.
+
+`juno ask approve` is refused: approving is `juno session approve <id>`, a
+separate command so that a permission rule allowing `juno ask` does not also let
+an agent approve the assistant's `call_service` on your behalf.
+`session approve` first checks that the session is waiting for an approval and
+exits 1 without sending anything otherwise. Any other message sent to a session
+waiting for an approval denies it, and the assistant sees the message as the
+reason.
+
+### `juno credential set`
+
+```bash
+juno credential set pushover_token                          # update an existing one
+juno credential set pushover_token --name Pushover --description "App token"
+```
+
+It reads the secret from the terminal with echo off and stores it. An existing
+credential keeps its name and description unless `--name` or `--description`
+replaces them; a new one needs both. It never prints the value.
+
+It **refuses to run when standard input is not a terminal** (exit 2), so an
+agent cannot pipe a value into it: a secret an agent types lands in its
+transcript. A person runs it, directly or as `! juno credential set <id>` inside
+Claude Code. For the same reason there is no tool that writes a credential.
+
+### `juno skill`
+
+`juno skill` lists the skills the assistant can load, one
+`<name> — <description>` line each. `juno skill <name>` prints one skill's body.
+`--json` prints the instance's JSON instead. The skills are the in-app
+assistant's, rendered for a reader outside Juno: where the assistant reads a
+tool name (`edit_state_layers`), you read the command in front of it
+(`juno state edit-layers`), or what to do in a working copy instead
+(`npm run deploy` for `submit_code`).
+
+### `juno agent-skill install`
+
+```bash
+juno agent-skill install                              # .claude/skills/juno/SKILL.md
+juno agent-skill install --dir ~/.claude/skills/juno  # for every project
+juno agent-skill install --allow-change               # + every change command
+juno agent-skill install --working-copy               # + the npm scripts (run it in a working copy)
+juno agent-skill install --agents-md >> AGENTS.md     # for a harness that reads AGENTS.md
+```
+
+Writes the skill that teaches a coding agent to use Juno — `SKILL.md` in the
+Agent Skills format, rendered by the instance (`GET /api/agent-skill`) — and
+prints a Claude Code permission block on stdout:
+
+```json
+{"permissions":{"allow":["Bash(juno discover:*)","Bash(juno related:*)","Bash(juno state get:*)",…]}}
+```
+
+The block is generated from the command table and each command's effect. By
+default it allows every `read` command. `--allow-change` adds every `change`
+command (layer stacks, devices, controls, `flow deploy`, …), for when you want
+the agent to reconfigure freely and use version history to review or undo.
+`--working-copy` adds the working copy's npm scripts of the same tiers
+(`npm test`, `npm run check`, and with `--allow-change` `npm run deploy`); those
+trust whatever that `package.json` says the script runs, so put them in the
+working copy's `.claude/settings.json`, never in user-wide settings. **An `act`
+command is never in the block**: it always prompts. Add one by hand if you want
+to, for example, let the agent press a test button. A command added in a later
+version prompts until you regenerate the block.
+
+The skill is short and stable; what changes per instance comes from `juno skill`
+and `--help` at run time. It records the version it was rendered at, and
+`juno skill`, `juno flow init` and `juno integration init` say on stderr when
+the instance serves a newer one. `--agents-md` prints the same text as an
+`AGENTS.md` section and writes nothing; `--json` prints the instance's answer.
+
+## Choosing an instance
+
+In order:
+
+1. `--url <url>`, before or after the command words;
+2. `$JUNO_URL`;
+3. `"juno": { "target": … }` in `package.json` in the working directory;
+4. the user config file, `$XDG_CONFIG_HOME/juno/config.json`
+   (`~/.config/juno/config.json` when `XDG_CONFIG_HOME` is unset).
+
+A project downloaded from a Juno already has the third, so a fresh clone deploys
+with no setup. `juno config set url <url>` writes the fourth, which is what
+makes `juno` useful outside a project. A bare host such as `juno.local:8080`
+means `http://juno.local:8080`.
+
+Every request carries an `X-Juno-Client` header: `cli`, or `cli/claude-code`
+when `CLAUDECODE=1` is set, as Claude Code sets it in the shells it starts. Juno
+records a write made through a tool as `operator:<client>`. The header names who
+made a change; it is not a security control.
+
+## Working copies
+
+A working copy is a directory on your machine holding one flow or one
+integration as files. Juno keeps every version, so the instance is the source of
+truth and a working copy is where you edit the next version. Its `package.json`
+names the instance (`juno.target`) and the flow or install it belongs to, so a
+fresh clone deploys with no setup.
+
+Both kinds have the same loop and the same npm scripts, and so does an app
+(`juno app init`), whose `check` stores a draft to preview at its `~draft/` URL:
+
+```bash
+npm install
+npm test               # local tsc, eslint and vitest
+npm run check          # ... then verify against the instance, which writes nothing
+npm run deploy         # verify, commit and activate the next version
+npm run pull           # bring the working copy up to the active version
+```
+
+| Script         | Flow working copy                                 | Integration working copy                                                  | App working copy                                  |
+| -------------- | ------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
+| `typecheck`    | `tsc --noEmit`                                    | `tsc --noEmit`                                                            | `tsc --noEmit && tsc --noEmit -p page`            |
+| `lint`         | `eslint .`                                        | `eslint .`                                                                | `eslint .`                                        |
+| `verify-types` | (absent)                                          | `juno integration verify-types`                                           | (absent)                                          |
+| `test`         | `npm run typecheck && npm run lint && vitest run` | `npm run verify-types && npm run typecheck && npm run lint && vitest run` | `npm run typecheck && npm run lint && vitest run` |
+| `types`        | `juno flow gen-types`                             | `juno integration gen-types`                                              | `juno app gen-types`                              |
+| `check`        | `juno flow check`                                 | `juno integration check`                                                  | `juno app check`                                  |
+| `deploy`       | `juno flow deploy`                                | `juno integration deploy`                                                 | `juno app deploy`                                 |
+| `watch`        | `juno flow deploy --watch`                        | `juno integration deploy --watch`                                         | `juno app deploy --watch`                         |
+| `pull`         | `juno flow pull`                                  | `juno integration pull`                                                   | `juno app pull`                                   |
+| `dev`          | (absent)                                          | (absent)                                                                  | `juno app dev`                                    |
+
+`dev` exists only in an app working copy, because flows and integrations have no
+page to serve. `npm run dev` serves the app on `http://localhost:8090/`
+(`--port <n>` picks another) with no instance, no credentials and no network:
+the page is built from `page/` on each request, the handlers run in Node through
+the testkit's `appHarness`, and live values come from a scenario file
+(`--scenario test/fixtures/<name>.json`). A panel beside the page sets values,
+presses controls and switches scenarios, and saving a file rebuilds and reloads.
+It uses the `esbuild` and `@junoflow/testkit` the working copy installs.
+
+`init` writes these lines as the instance renders them. After that they are
+yours: `pull` never changes `scripts`. To see the current lines, run `init` into
+a fresh directory and compare.
+
+The working-copy commands sit in the `flow` and `integration` groups beside the
+commands that act on the instance, and `juno flow --help` and
+`juno integration --help` list them under their own heading. Every one except
+`init` acts on the working copy in the current directory and refuses an
+argument: `juno flow deploy porch-light` exits 2 and tells you to run
+`juno flow init porch-light` and deploy from inside it.
+
+| Effect   | Commands                                                             |
+| -------- | -------------------------------------------------------------------- |
+| `read`   | `init`, `gen-types`, `verify-types`, `check`, `pull`, `flow fixture` |
+| `change` | `deploy`: it adds a version to the flow's or install's history       |
+| `local`  | `app dev`: a server on localhost that touches no instance            |
+
+`init`, `pull` and `flow fixture` write local files, but change nothing in Juno,
+so their effect is `read`.
+
+After writing a working copy, `init` prints the skills for writing that kind,
+one `<name> — <description>` line each, the same index Juno's in-app flow or
+integration author is given; load one with `juno skill <name>`.
+`juno flow --help` and `juno integration --help` list them too.
+
+### What Juno stores, and what `pull` writes
+
+A working copy holds three kinds of file:
+
+| Kind      | Files                                                                                             | Stored by Juno                         |
+| --------- | ------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| artifact  | `manifest.json`, `src/**`, `test/**`                                                              | yes, with every version, byte for byte |
+| generated | `types/**`                                                                                        | no; generated from the manifest        |
+| project   | everything else: `tsconfig.json`, `eslint.config.js`, `README.md`, `.gitignore`, `package.json` … | no                                     |
+
+`check` and `deploy` send the artifact files. Your tests travel with the
+version, so a copy pulled elsewhere gets them back. Juno stores `test/**` and
+nothing more: it never type-checks, lints or runs a test. `npm test` runs them
+in your checkout.
+
+`pull` makes the artifact files the active version's, exactly as Juno stores
+them, and regenerates `types/`. It deletes a local file only when Juno deleted
+it: the version recorded in `juno.base_version` had the file and the pulled
+version does not. A file neither version has is one you have not deployed yet,
+and `pull` leaves it alone. A working copy with no `base_version` has nothing to
+compare against, so `pull` deletes nothing. It prints what it wrote and, on a
+second line, what it removed:
+
+```text
+pulled porch-light v7 from http://juno.local:8080 (manifest.json, package.json, src/flow.ts)
+removed src/old.ts
+```
+
+`pull` never writes or deletes a project file. In `package.json` it sets two
+keys, `juno.base_version` and `dependencies` (from the manifest), and leaves the
+rest as you wrote it. An integration whose manifest declares no dependencies
+keeps them in `package.json` alone, so there `pull` leaves `dependencies` as it
+is. It refuses to overwrite uncommitted changes in a git working tree unless you
+pass `--force`.
+
+## Flows as files
+
+```bash
+juno flow init porch-light          # the flow's active version, or a stub for a new id
+cd porch-light && npm install
+$EDITOR src/flow.ts manifest.json
+npm test
+npm run check
+npm run deploy
+```
+
+`juno flow init <id>` writes `./<id>` (or the current directory, with `--here`).
+For a flow that has an active version, it is that version. For a new id it is a
+stub whose only trigger is a `call` trigger, so a stub deployed by accident
+never fires on its own. When the version stores no `test/**`, `init` also writes
+a starter `test/flow.test.ts`: a conformance test against `@junoflow/testkit`'s
+`flowHarness`, and one `it.todo` per trigger. A working copy has the same shape
+as an integration's:
+
+| File                  | What it is                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| `manifest.json`       | the flow's manifest                                                                        |
+| `src/flow.ts`         | the flow's entry                                                                           |
+| `src/**`              | any other `.ts` or `.json` module the entry imports                                        |
+| `test/**`             | your tests and their `.ts` or `.json` fixtures; stored with the flow, never compiled       |
+| `types/flow-env.d.ts` | the module the source imports its types from, generated from the manifest and the instance |
+| `types/flow-api.d.ts` | the SDK's generic declarations, which `flow-env.d.ts` fills in; never import it directly   |
+| `tsconfig.json`       | extends `@junoflow/cli/tsconfig.base.json`                                                 |
+| `eslint.config.js`    | `@junoflow/cli/eslint.flow.config.js`: the rules Juno's verify step lints flows by         |
+| `package.json`        | the scripts, the dependencies, and `juno.target` / `flow_id` / `base_version`              |
+| `.gitignore`          | `node_modules/`                                                                            |
+
+Every source file imports its types from the generated module:
+
+```ts
+// src/flow.ts
+import type { Flow } from '../types/flow-env';
+import { describe } from './describe';
+
+export default {
+  triggers: {
+    onCall: async ({ status }) => status.ok(describe()),
+  },
+} satisfies Flow;
+```
+
+`src/` and `test/` hold `.ts` and `.json` files only, at most 64 of them
+together, each at most 512 KiB. Every one is sent on `check` and `deploy`. The
+files under `src/` are type-checked and linted, and only `src/flow.ts` must
+contain `satisfies Flow`. The files under `test/` are stored as they are; the
+flow's `eslint.config.js` skips them too. `types/` is generated and is never
+sent.
+
+| Command                                         | What it does                                                                           |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `juno flow init <id> [--here]`                  | write a working copy from the instance                                                 |
+| `juno flow gen-types`                           | regenerate `types/flow-env.d.ts` and `types/flow-api.d.ts` from `manifest.json`        |
+| `juno flow check [--skip-local] [--json]`       | local `tsc --noEmit` and `eslint .`, then verify against the instance, writing nothing |
+| `juno flow deploy [--watch] [--force] [--json]` | verify, commit and activate; write back the manifest, the types and `base_version`     |
+| `juno flow pull [--force]`                      | bring the working copy up to the active version                                        |
+| `juno flow fixture --run <seq> [--force]`       | write run `seq` as a test fixture, `test/fixtures/<flow-id>-<seq>.json`                |
+
+`pull` writes `manifest.json`, `src/**`, `test/**` and both `types/` files, and
+deletes what the flow deleted (see
+[What Juno stores](#what-juno-stores-and-what-pull-writes)).
+
+`deploy` writes back what Juno stored: the canonical `manifest.json`, freshly
+generated types, and the new version number. `--watch` redeploys whenever a file
+under `src/` or `manifest.json` is saved (a deploy sends `test/` too, but saving
+a test does not start one), skips a save that changed nothing, and keeps
+watching after a failure. `--json` on `check` and `deploy` prints the instance's
+JSON answer (or, when verification fails, its diagnostics) on stdout instead,
+for CI; the integration commands take it too.
+
+`fixture` turns a recorded run into a scenario a test loads with
+`h.scenario(fixture)` from `@junoflow/testkit`: the event the run received, the
+world it saw as far as Juno recorded it, and, under `expect`, the status, steps
+and target calls it produced. It writes the file the instance builds, prints
+`wrote test/fixtures/porch-light-42.json`, and lists on stderr each thing the
+run did not record, such as a state value reconstructed from history or a
+credential to fill in. It refuses to overwrite an existing fixture without
+`--force` (exit 1), warns when the run ran another version than
+`juno.base_version`, and exits 1 with the instance's reason for a run it cannot
+replay: one still going, one that slept or waited for an event, or one that was
+cancelled.
+
+### The flow id and `base_version`
+
+`package.json`'s `juno.flow_id` binds the working copy to one flow. The
+manifest's `id` is the flow's identity, so a manifest whose `id` differs from
+`flow_id` is refused, naming both. To change what a flow is called, edit `name`;
+renaming a flow is done in the UI.
+
+`juno.base_version` is the version the working copy came from. `deploy` sends
+it, and when the flow's active version is anything else (someone edited the flow
+in the UI, asked the assistant to change it, or rolled it back), Juno refuses
+the deploy and the CLI exits **4**, naming both versions. Run `npm run pull` to
+start from the active version, or `juno flow deploy --force` to replace it.
+`check` makes the same comparison, so a stale working copy shows up before you
+deploy. A new flow's working copy has no `base_version`. `juno flow pull` on a
+flow with no active version exits 1: there is nothing to pull.
+
+### Dependencies
+
+`manifest.dependencies` is the list Juno installs when it verifies the flow.
+`init` copies it into `package.json`'s `dependencies` so `npm install` gives
+`tsc` the same modules. Add a package to the manifest, then to `package.json`
+(or deploy and `npm run pull`). `juno flow check` warns when the two lists
+differ, naming the packages.
+
+### Why there is no `flow verify-types`
+
+`types/flow-env.d.ts` describes the instance as well as the manifest: the states
+the flow binds, the integrations and controls it calls. It goes stale whenever
+the instance changes, and Juno regenerates it on every check and deploy, so
+stale local types never ship. `npm run types` refreshes your copy when the
+editor disagrees with the instance.
+
+## Developing integrations
+
 An integration is a git repository holding `manifest.json` and TypeScript. Juno
 fetches it at a tag, compiles it, and runs it in a sandbox. There is no
 packaging format and nothing is published to npm.
 
-## Commands
+```bash
+npm install --global @junoflow/cli
+juno integration init my-integration --url http://juno.local:8080
+```
 
-| Command                 | What it does                                                                   |
-| ----------------------- | ------------------------------------------------------------------------------ |
-| `juno init <name>`      | fetch a starting project from a Juno and write it down                         |
-| `juno types`            | POST `manifest.json`, write `types/`                                           |
-| `juno verify-types`     | check `types/` still matches `manifest.json` — talks to nothing                |
-| `juno check`            | local `verify-types` + `tsc --noEmit` + `eslint`, then validate against a Juno |
-| `juno deploy [--watch]` | upload, verify, activate — and write back the returned types                   |
-| `juno pull`             | write back the manifest and sources the instance holds                         |
+### Commands
+
+| Command                                                            | What it does                                                                   |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `juno integration init <id> [--name <name>] [--here]`              | write the install's project from a Juno, or a starter for a new id             |
+| `juno integration gen-types`                                       | POST `manifest.json`, write `types/`                                           |
+| `juno integration verify-types`                                    | check `types/` still matches `manifest.json`; talks to nothing                 |
+| `juno integration check [--skip-local] [--id <id>] [--json]`       | local `verify-types` + `tsc --noEmit` + `eslint`, then validate against a Juno |
+| `juno integration deploy [--watch] [--force] [--id <id>] [--json]` | upload, verify, activate, and write back the returned types and `base_version` |
+| `juno integration pull [--force] [--id <id>]`                      | write back the manifest, `src/`, `test/`, `types/` and `base_version`          |
+
+They exit as the [exit-code table](#exit-codes) says: 1 for a failed check or
+deploy, 2 for a usage error, 3 when the instance is unreachable, 4 for a stale
+working copy (see [`base_version`](#base_version)).
 
 ### Options
 
-| Flag            | Meaning                                                              |
-| --------------- | -------------------------------------------------------------------- |
-| `--url <url>`   | the instance to talk to                                              |
-| `--name <name>` | address an install under a different name than the manifest declares |
-| `--watch`       | redeploy on every save (`deploy`)                                    |
-| `--force`       | overwrite a dirty working tree (`pull`)                              |
-| `--here`        | scaffold into the current directory (`init`)                         |
-| `--skip-local`  | skip the local verify-types/tsc/eslint pass (`check`)                |
+| Flag            | Meaning                                                                                                     |
+| --------------- | ----------------------------------------------------------------------------------------------------------- |
+| `--url <url>`   | the instance to talk to                                                                                     |
+| `--id <id>`     | address an install under a different id than the manifest declares (`check`, `deploy`, `pull`)              |
+| `--name <name>` | display name for a new integration (`init`)                                                                 |
+| `--watch`       | redeploy on every save (`deploy`)                                                                           |
+| `--force`       | overwrite a dirty working tree (`pull`); replace the active version whatever the base (`deploy`)            |
+| `--here`        | scaffold into the current directory (`init`)                                                                |
+| `--skip-local`  | skip the local verify-types/tsc/eslint pass (`check`)                                                       |
+| `--json`        | print the instance's JSON answer (or the failed verify's diagnostics) on stdout, for CI (`check`, `deploy`) |
 
-## Choosing an instance
+### `base_version`
 
-In order: `--url`, then `$JUNO_URL`, then `"juno": { "target": … }` in
-`package.json`. A project downloaded from a Juno already has the third, so a
-fresh clone deploys with no setup.
+`package.json`'s `juno.base_version` is the version the working copy was pulled
+from or last deployed. `init` of an installed id, the **Download project** zip,
+`pull` and every successful `deploy` write it. `deploy` and `check` send it, and
+when the install's active version is anything else (someone deployed another
+copy, asked the assistant to change the integration, or rolled it back), Juno
+refuses and the CLI exits **4**:
 
-Juno has **no authentication on any endpoint**. An instance is a trusted-LAN
-appliance; do not expose one to the internet.
+```text
+integration "pushover": active version is v4, but this working copy was pulled from v3 — pull it again, or deploy with --force to replace it
+```
+
+Run `npm run pull` to start from the active version, or
+`juno integration deploy --force` to replace it. A working copy without a
+`base_version` sends none; its first deploy or pull records one.
+
+The base belongs to the install `manifest.json` names. `--id <other>` deploys
+the same code to a different install, whose versions this copy has never seen,
+so it sends no base, writes none back, and warns
+`no stale-base check: deploying to <other>, not <manifest id>`. It needs no
+`--force`. `pull --id <other>` rewrites `manifest.json` to that install, so
+later deploys are checked against it.
 
-## The loop
+### The loop
 
 ```bash
-npm run watch          # juno deploy --watch
+npm run watch          # juno integration deploy --watch
 ```
 
 Add an action to `manifest.json`. The types regenerate, and your editor
@@ -54,7 +693,7 @@ immediately red-squiggles `src/integration.ts` because `IntegrationActions` now
 requires a method you have not written — with the parameter and return types
 your JSON Schema implies. The manifest drives the types drive the compiler.
 
-## Why the types are committed
+### Why the types are committed
 
 `types/` is generated and checked in. CI needs no Juno, a fresh clone compiles
 offline, and the diff in a pull request shows that adding an action changed the
@@ -69,40 +708,42 @@ contract you no longer declare. `tsc` compiles happily against stale types,
 with your _module_, never with `types/` — so the mismatch surfaces at deploy, or
 later, as a flow author calling an action whose shape changed.
 
-`juno verify-types` closes it. `juno types` records a fingerprint of the
-`manifest.json` it generated from, as a comment in `types/integration-env.d.ts`:
+`juno integration verify-types` closes it. `juno integration gen-types` records
+a fingerprint of the `manifest.json` it generated from, as a comment in
+`types/integration-env.d.ts`:
 
 ```ts
 // integration-env.d.ts for 'pushover'
-// DO NOT EDIT — generated by 'juno types' from 'manifest.json'.
+// DO NOT EDIT — generated by 'juno integration gen-types' from 'manifest.json'.
 // juno:manifest-sha256 5c5ca8eabe12cf44
 ```
 
 `verify-types` recomputes it and compares. It runs first in `npm test` and
-inside `juno check`, and it contacts nothing — which is the point: the mistake
-is caught in a contributor's CI, and that CI deliberately has no instance to
-ask. Reformatting `manifest.json` also invalidates the stamp; the fix is the
-same `npm run types` either way.
+inside `juno integration check`, and it contacts nothing — which is the point:
+the mistake is caught in a contributor's CI, and that CI deliberately has no
+instance to ask. Reformatting `manifest.json` also invalidates the stamp; the
+fix is the same `npm run types` either way.
 
-## What runs where
+### What runs where
 
-|                                                                 | offline | needs an instance |
-| --------------------------------------------------------------- | ------- | ----------------- |
-| `tsc --noEmit`, `eslint`, `vitest`                              | ✅      |                   |
-| `juno verify-types` (is `types/` current?)                      | ✅      |                   |
-| structural manifest check via `"$schema"` in your editor        | ✅      |                   |
-| reserved names, cross-surface collisions, JSON Schema compiling |         | `juno check`      |
-| `juno init`, `juno types`, `juno deploy`                        |         | ✅                |
+|                                                                 | offline | needs an instance        |
+| --------------------------------------------------------------- | ------- | ------------------------ |
+| `tsc --noEmit`, `eslint`, `vitest`                              | ✅      |                          |
+| `juno integration verify-types` (is `types/` current?)          | ✅      |                          |
+| structural manifest check via `"$schema"` in your editor        | ✅      |                          |
+| reserved names, cross-surface collisions, JSON Schema compiling |         | `juno integration check` |
+| `juno integration init`, `gen-types`, `deploy`                  |         | ✅                       |
 
 Everything semantic lives in the Go server. This package knows some HTTP
 endpoints and a config preset — that is deliberate, so there is one answer to
 "is this manifest valid" rather than two that can disagree.
 
-## `init` vs. downloading a project
+### `init` vs. downloading a project
 
-Both produce the same project, from the same generator on the instance: `init`
-starts from a stub manifest, the **Develop locally → Download project** button
-starts from an integration that already exists there. Neither is a local
-template — the CLI writes the files it is handed, so a scaffold cannot drift
-from what the server ejects. To refresh an existing checkout use `juno pull`; a
-second download would clobber your working tree.
+Both produce the same project, from the same generator on the instance. `init`
+of an id that is already installed writes that install's project, the one the
+**Develop locally → Download project** button gives you; `init` of a new id
+writes a starter. Neither is a local template: the CLI writes the files it is
+handed, so a scaffold cannot drift from what the server ejects. To refresh an
+existing checkout use `juno integration pull`, which touches only the files Juno
+stores; a second download would clobber your working tree.