octwin-cli 0.8.13 → 0.8.14

package/README.md

@@ -62,6 +62,11 @@ octwin status               # "✓ live and current" once it's warm
 
 ## Commands
 
+**`--json` puts the result on stdout and nothing else.** Progress lines, tables and hints go to stderr,
+so `octwin records lead --json | jq` always parses. A command that prints a stream (`chat`, `login`)
+writes one JSON object per line. `--json` on a command with no JSON output (`deploy`, `whoami`, …) is
+refused by name rather than leaving stdout empty.
+
 | Command | What it does |
 | --- | --- |
 | `octwin init <dir>` | Scaffold a new pure-YAML pack into `<dir>` (writes a starter `manifest.yaml`, flow, prompt, `.gitignore` and `README.md` — pack content only). Options: `--id`, `--description`, `--display-name`. |
@@ -73,7 +78,7 @@ octwin status               # "✓ live and current" once it's warm
 | `octwin pull <packId>` | Write a **deployed** pack's source back to disk — the inverse of `deploy`, and how a pack pushed from one machine is recovered. Defaults to the version installed on the target project; `--version` overrides, `--dir` defaults to `./<packId>`, a non-empty dir needs `--force`. You may pull a pack your tenant **owns**. |
 | `octwin chat "msg"` | Drive a turn through the dev web channel and print **every render with its tap ids**. `--as <handle>` picks the test user; `--tap "<tap-id>"` presses a rendered button/list row; `--json` dumps the raw envelopes. Each reply line says who sent it: plain `← …` is the AI Agent, `← [notify] …` a reminder or notification (never taken for the turn's reply), `← [operator: Name] …` a person in Live chat, `← [platform] …` a handoff line. |
 | `octwin logs` | List recent conversations (handle, status, last activity; `--as` filters), or show one conversation's full event timeline — including what each turn rendered. `--json` for raw payloads. |
-| `octwin records` | Inspect the pack's XRM data (needs a `records:read` token). No args = list entities. Writes (`records:write`): `create`, `patch`, `stage`, `note`, and `archive <id>` / `restore <id>` — there is no delete; archive takes a record (test data too) out of every list and count, and restore brings it back. |
+| `octwin records` | Inspect the pack's XRM data (needs a `records:read` token). No args = list entities. `<entity> --search "<words>"` runs the entity's ranked search (it must declare `search:`) and prints each match's score. Writes (`records:write`): `create`, `patch`, `stage`, `note`, and `archive <id>` / `restore <id>` — there is no delete; archive takes a record (test data too) out of every list and count, and restore brings it back. |
 | `octwin work` | The work inbox: worked records across queues, one item + its timeline and decisions, or `--queues` for queue keys + open counts. Casework is one shape of it — the command spans every entity a pack works. |
 | `octwin projects` | The `--project <slug>` values this token can name, with the plan's project cap. `--archived` includes archived ones. A `pack:deploy` token reaches it — it names a project in every other command, so this turns "guess the slug" into "read the list". |
 | `octwin agents` | The agent roster with each agent's **effective** model / history window and **which layer set it** (project override → platform default → pack manifest) — an operator platform default can override what your manifest declares. `--prompt` prints the exact system prompt the LLM sees. Needs `agents:read`. |