docs(logs): explain why the stream can look empty, and split out automation

Reported as 'logs prints the banner and nothing else'. Traced with a raw
websocket probe: the subscription is accepted, frames do arrive, and the
command prints them — verified by running iob-sync logs while opening a
second connection, which Admin logs at info and which appeared immediately.

The stream was not broken; the house was quiet. Reading the instance
objects showed javascript.1/2/3 all at loglevel=info, and the adapter's
'script recompiled / started / stopped' messages are debug-level, so they
were never emitted. A push therefore looks silent even when it worked.

--level made that worse by implying it could reveal them. It only narrows
what the server already sends, so it now says so when debug or silly is
requested, and points at the instance log level in Admin.

README gains an 'If logs shows nothing' section with a way to prove the
stream is alive, and the --json deep dive moves to docs/AUTOMATION.md with
a short pointer, plus a Docs index. All anchors and relative links checked;
the only broken one is the screenshot placeholder, which is deliberate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: mschmicking

README.md

@@ -62,6 +62,7 @@ The five commands worth knowing on day one:
 - [Safety model](#safety-model)
 - [Authentication](#authentication)
 - [Scripting and automation](#scripting-and-automation)
+- [Docs](#docs)
 - [Known limitations](#known-limitations)
 - [Development](#development)
 
@@ -203,6 +204,21 @@ iob-sync logs garage           # only lines mentioning "garage"
 iob-sync logs --level error    # only failures
 ```
 
+#### If `logs` shows nothing
+
+It is streaming; there is simply nothing to show. Two things surprise people:
+
+- **`--level` only narrows what the server already sends.** An ioBroker adapter emits
+  nothing below _its own_ configured log level, so asking for `--level debug` while
+  `javascript.0` runs at `info` produces silence. Raise it in **Admin → Instances →
+  your javascript instance → log level**.
+- **"script recompiled / started / stopped" messages are debug-level**, so at the default
+  `info` they are never emitted at all — a `push` looks silent even though it worked.
+  Your own `log()` calls are info and do appear.
+
+To prove the stream is alive, run `iob-sync logs` and open a second terminal running any
+`iob-sync` command: Admin logs every connection at info, so a line appears immediately.
+
 ## Commands
 
 **Sync**
@@ -306,35 +322,16 @@ Connect to the **admin adapter** port (usually 8081), not the socket.io adapter
 
 ## Scripting and automation
 
-Human output is for reading; `--json` is for everything else. It emits
-[NDJSON](https://ndjson.org) on stdout — one JSON object per line, each tagged with a
-`type`. Human text is suppressed and warnings/errors stay on stderr, so **stdout stays
-parseable even when a command fails**.
-
-What that is actually for:
+`--json` puts [NDJSON](https://ndjson.org) on stdout — one JSON object per line, each
+tagged with a `type`. Human text is suppressed and warnings/errors stay on stderr, so
+**stdout stays parseable even when a command fails**.
 
 ```bash
 # Fail a CI job if anything drifted from git
 test -z "$(iob-sync --json status | jq -rc 'select(.state != "in-sync")')"
-
-# Alert if a script got disabled behind your back
-iob-sync --json list | jq -r 'select(.enabled | not) | .id'
-
-# Nightly backup, reporting where the snapshot went
-iob-sync --json backup | jq -r .snapshot
-
-# Follow only errors, as structured events
-iob-sync --json logs --level error
 ```
 
-It is also what makes the tool usable by a coding agent: an agent editing your scripts
-can read `status`, push, and then watch `logs` for a compile failure, without
-screen-scraping a table meant for a terminal.
-
-Records carry underlying values rather than display strings — `enabled` is a boolean, not
-`"✓"`; `engine` is the full instance id, not `js.2`; and `--json status` includes the
-in-sync scripts the human view collapses into a count. NDJSON rather than one array
-because `logs` and `watch` never end; use `jq -s .` if you want a single document.
+See **[docs/AUTOMATION.md](docs/AUTOMATION.md)** for the record shapes and more examples.
 
 ## Known limitations
 
@@ -400,6 +397,13 @@ Every test runs against an in-process fake Admin server (`test/fake-server.ts`);
 touches a real instance. `AGENTS.md` documents the architecture, the wire protocol, and
 the safety invariants any change has to preserve — read it before changing sync logic.
 
+## Docs
+
+- **[docs/AUTOMATION.md](docs/AUTOMATION.md)** — `--json` record shapes, CI and agent usage
+- **[docs/GOING-PUBLIC.md](docs/GOING-PUBLIC.md)** — release checklist (maintainers)
+- **[AGENTS.md](AGENTS.md)** — architecture, wire protocol, safety invariants
+- **[CHANGELOG.md](CHANGELOG.md)**
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

docs/AUTOMATION.md

@@ -0,0 +1,34 @@
+# Scripting and automation
+
+Machine-readable output, and what it is for. See the
+[README](../README.md) for everything else.
+
+Human output is for reading; `--json` is for everything else. It emits
+[NDJSON](https://ndjson.org) on stdout — one JSON object per line, each tagged with a
+`type`. Human text is suppressed and warnings/errors stay on stderr, so **stdout stays
+parseable even when a command fails**.
+
+What that is actually for:
+
+```bash
+# Fail a CI job if anything drifted from git
+test -z "$(iob-sync --json status | jq -rc 'select(.state != "in-sync")')"
+
+# Alert if a script got disabled behind your back
+iob-sync --json list | jq -r 'select(.enabled | not) | .id'
+
+# Nightly backup, reporting where the snapshot went
+iob-sync --json backup | jq -r .snapshot
+
+# Follow only errors, as structured events
+iob-sync --json logs --level error
+```
+
+It is also what makes the tool usable by a coding agent: an agent editing your scripts
+can read `status`, push, and then watch `logs` for a compile failure, without
+screen-scraping a table meant for a terminal.
+
+Records carry underlying values rather than display strings — `enabled` is a boolean, not
+`"✓"`; `engine` is the full instance id, not `js.2`; and `--json status` includes the
+in-sync scripts the human view collapses into a count. NDJSON rather than one array
+because `logs` and `watch` never end; use `jq -s .` if you want a single document.

src/commands/logs.ts

@@ -74,11 +74,24 @@ export async function logs(ctx: CommandContext, opts: LogsOptions = {}): Promise
 
   // Announced before subscribing, not after: the server logs our own connection, so
   // a line can arrive while `subscribe` is still in flight and print above the banner.
+  const level = parseLevel(opts.level);
   ctx.log.info(
     `Streaming logs from ${ctx.config.url}${opts.pattern ? ` matching "${opts.pattern}"` : ''} ` +
-      `at level ${parseLevel(opts.level)} and above.`,
+      `at level ${level} and above.`,
   );
 
+  // This filter only narrows what the server already sends. An adapter emits nothing
+  // below its own configured log level, so asking for debug here while javascript.2
+  // runs at info yields silence — and the flag makes it look like the tool is broken
+  // rather than that the messages were never sent.
+  if (level === 'debug' || level === 'silly') {
+    ctx.log.info(
+      `Note: ${level} lines only appear if the adapter itself is set to ${level} ` +
+        '(ioBroker Admin → Instances → the javascript instance → log level). ' +
+        'Script recompile/start/stop messages are debug-level.',
+    );
+  }
+
   await ctx.socket.subscribeLog((entry) => {
     if (severityRank(entry.severity) < minRank) return;
     if (!matches(entry, opts.pattern)) return;