@junoflow/cli 0.3.0 → 0.6.0

package/README.md

@@ -1,52 +1,575 @@
 # @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
 ```
 
-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.
+The package installs one command, `juno`, with two sets of commands:
 
-## 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).
 
-| 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                         |
+Juno has **no authentication on any endpoint**. An instance is a trusted-LAN
+appliance; do not expose one to the internet.
 
-### Options
+## 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.
+
+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    | `juno flow deploy` / `flow check`: the flow changed on the instance 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.
 
-| 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`)                |
+```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: `--url`, then `$JUNO_URL`, then `"juno": { "target": … }` in
-`package.json`. A project downloaded from a Juno already has the third, so a
+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.
 
-Juno has **no authentication on any endpoint**. An instance is a trusted-LAN
-appliance; do not expose one to the internet.
+Both kinds have the same loop and the same npm scripts:
+
+```bash
+npm install
+npm test               # local tsc and eslint
+npm run check          # ... then verify against the instance, which writes nothing
+npm run deploy         # verify, commit and activate the next version
+npm run pull           # overwrite the working copy with the active version
+```
+
+| Script         | Flow working copy                   | Integration working copy                                                  |
+| -------------- | ----------------------------------- | ------------------------------------------------------------------------- |
+| `typecheck`    | `tsc --noEmit`                      | `tsc --noEmit`                                                            |
+| `lint`         | `eslint .`                          | `eslint .`                                                                |
+| `verify-types` | (absent)                            | `juno integration verify-types`                                           |
+| `test`         | `npm run typecheck && npm run lint` | `npm run verify-types && npm run typecheck && npm run lint && vitest run` |
+| `types`        | `juno flow gen-types`               | `juno integration gen-types`                                              |
+| `check`        | `juno flow check`                   | `juno integration check`                                                  |
+| `deploy`       | `juno flow deploy`                  | `juno integration deploy`                                                 |
+| `watch`        | `juno flow deploy --watch`          | `juno integration deploy --watch`                                         |
+| `pull`         | `juno flow pull`                    | `juno integration pull`                                                   |
+
+The instance writes these lines, and `pull` rewrites them, so a working copy
+picks up a new command without your editing `package.json`.
+
+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`           |
+| `change` | `deploy`: it adds a version to the flow's or install's history |
+
+`init` and `pull` 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. `pull` 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 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. A working copy is flat:
+
+| File               | What it is                                                                         |
+| ------------------ | ---------------------------------------------------------------------------------- |
+| `manifest.json`    | the flow's manifest                                                                |
+| `flow.ts`          | the flow's source                                                                  |
+| `flow-env.d.ts`    | types generated from the manifest and the instance's states, integrations, etc.    |
+| `flow-api.d.ts`    | the SDK's declarations; it and `flow-env.d.ts` only typecheck together             |
+| `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/`                                                                    |
+
+| Command                                         | What it does                                                                           |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `juno flow init <id> [--here]`                  | write a working copy from the instance                                                 |
+| `juno flow gen-types`                           | regenerate `flow-env.d.ts` and `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]`                      | overwrite the working copy with the active version                                     |
+
+`deploy` writes back what Juno stored: the canonical `manifest.json`, freshly
+generated types, and the new version number. `--watch` redeploys whenever
+`flow.ts` or `manifest.json` is saved, 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.
+
+### 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`
+
+`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.
+
+```bash
+npm install --global @junoflow/cli
+juno integration init my-integration --url http://juno.local:8080
+```
+
+### 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] [--id <id>] [--json]`     | upload, verify, activate, and write back the returned types                    |
+| `juno integration pull [--force] [--id <id>]`                | write back the manifest, sources and `package.json` scripts the instance holds |
+
+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.
+
+### Options
+
+| 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`)                                                                     |
+| `--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`) |
 
-## 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 +577,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 +592,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 also rewrites
+`package.json`'s `scripts`; a second download would clobber your working tree.