@cabane/companion 0.6.101 → 0.6.102

package/README.md

@@ -69,7 +69,7 @@ Open the printed URL, enter the code in **Settings → Connectors**, give the de
 
 cabane-companion start
 #   ✓ Cabane companion is running in the background.
-#     Stop:  cabane-companion stop        Logs:  ~/.cabane/companion.log
+#     Stop:  cabane-companion stop        Logs:  cabane-companion logs   (~/.cabane/companion.log)
 ```
 
 A headless machine needs no browser of its own: run `cabane-companion pair` on it, then open **Settings → Connectors** in any browser you're signed in to and enter the short code it printed. The device token is delivered straight to the waiting CLI over the pairing channel — nothing is ever copied or pasted.
@@ -85,6 +85,7 @@ A freshly paired device runs nothing yet — it has no agents. In **Workspace se
 | `connect <claude-code\|codex\|opencode>` | Connect a detected coding harness now or update the running Companion over its control socket.                                                                                                                                                                 |
 | `stop`                                   | Stop a foreground or detached Companion cleanly. Idempotent — "nothing running" is a success.                                                                                                                                                                  |
 | `status`                                 | Print the paired device, log/transcript paths, process mode, pid and uptime, declared secret names, and local overrides.                                                                                                                                       |
+| `logs [-n N] [-f]`                       | Show recent log lines or follow new ones.                                                                                                                                                                                                                      |
 | `transcript [file] [--last] [-f]`        | Show a recent full agent transcript. No args lists recent turns; `--last` renders the newest; `--follow` live-watches new turns.                                                                                                                               |
 | `logout [-y] [--purge]`                  | Remove the device token and cached agent credentials. `--purge` removes the whole local config. Neither removes the device from Cabane.                                                                                                                        |
 | `--version` / `-V`                       | Print the Companion version.                                                                                                                                                                                                                                   |
@@ -98,7 +99,7 @@ In an interactive terminal, `cabane-companion start` backgrounds itself, returns
 ```sh
 cabane-companion start
 #   ✓ Cabane companion is running in the background.
-#     Stop:  cabane-companion stop        Logs:  ~/.cabane/companion.log
+#     Stop:  cabane-companion stop        Logs:  cabane-companion logs   (~/.cabane/companion.log)
 ```
 
 `start --daemon` takes the same path for compatibility. This detached process does not survive logout or reboot and Cabane does not install, enable, or update a login service. Use `cabane-companion status` to check it and `cabane-companion stop` to stop it.
@@ -336,11 +337,30 @@ Everything else about a Companion-run agent is the same whichever harness runs i
 ├── outbox/<workspace_id>/ # durable per-agent commit queue — a reply survives a transient API outage
 ├── runtime.json           # written while `start` runs: control socket + pid (swept on exit)
 ├── transcripts/           # one JSONL file per dispatch — the full agent turn (see below)
-└── companion.log          # rolling JSON-lines log
+└── companion.log          # readable event log (JSON opt-in)
 ```
 
 No SQLite, no embedded DB. Cabane is the source of truth for which agents to run and how they're configured.
 
+## Logs
+
+`cabane-companion logs` shows the last 50 lines. Use `-n 20` for twenty lines or
+`-f` to follow new lines until Ctrl-C. The initial read is capped at 1 MiB.
+The file is `~/.cabane/companion.log` and is human-readable by default: local
+`HH:MM:SS`, a level word for warnings and errors, then a sentence. Turns include
+the agent's name and an eight-character conversation id. Failed turns include
+a reason, the next step and the transcript path.
+
+- `info` (default): startup, connection, assigned agents, and turn outcomes.
+- `warn`: degraded operation, such as reconnecting or updates waiting to arrive.
+- `debug`: internal diagnostics for investigating a problem. Errors are always shown.
+
+Choose with `cabane-companion start --log-level debug` or `"logLevel": "debug"`
+in `~/.cabane/config.json`. Config changes apply on reload; a start flag wins.
+Use `--log-format json` or `"logFormat": "json"` for machine-readable JSON with
+full ids. The default is `human`; the terminal always stays human-readable.
+Log files append across starts. Transcripts remain JSONL in either mode.
+
 ## Debugging a turn: transcripts
 
 Cabane shows the agent's final reply, but not _how_ it got there. When a turn misbehaves — an agent that "couldn't read the file", a tool that errored, MCP tools that didn't load, a missing secret — the full picture is on disk. Every dispatch — on whichever harness ran it — writes the complete turn stream (the system init with its tool list, every tool call **and its result**, the assistant text, the outcome) to a JSONL file under `~/.cabane/transcripts/`. On a failed turn, the Companion log also prints the exact path.