@lotics/cli 0.114.0 → 0.123.0

package/AGENTS.md

@@ -48,6 +48,10 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   `workspace doctor` on findings. Scripts can gate on them.
 - **Text output is the default and is built for reading**; reach for `--json` only when a field is
   needed programmatically.
+- **`LOTICS_TELEMETRY=1` correlates a whole session** so the authoring loop's rough edges can be
+  found and fixed. Off by default; set it in the shell profile, not per command (each invocation is
+  its own process). It sends no arguments, no file contents, and no record data — see README
+  § Diagnostics.
 
 ## Where this CLI is not the answer
 

package/README.md

@@ -103,6 +103,19 @@ Every command names its target before it acts — `lotics → <org> / <workspace
 
 `LOTICS_WORKSPACE` (or `--workspace <id>` / `-w`) overrides the workspace at any level. For ephemeral or CI use, set `LOTICS_API_KEY` instead of saving anything.
 
+### Diagnostics
+
+Every request identifies the CLI (`user-agent: lotics-cli/<version> node/<v> <platform>`) and names the command that made it (`x-lotics-cli-command: app.workflow.set`), so a failure in the server's logs can be traced to the verb and version that produced it. Neither header carries arguments: the command chain stops before any id, path, `@file`, or JSON payload.
+
+**`LOTICS_TELEMETRY=1` additionally records the session.** Off by default. Set it in your shell profile rather than per command — each invocation is its own process. When set:
+
+- Requests carry a session id shared by every command in the sitting — under an agent harness it adopts the harness's own session id, otherwise it rolls over after 30 minutes idle (`~/.lotics/session.json`).
+- Each invocation appends one record to `~/.lotics/telemetry.ndjson` — the command, its exit code, how long it took, and, on a failure, the message that was printed. Batches are sent on a later run; a failed send is retried, never dropped silently.
+
+Arguments contribute a **hash** and a **shape** (`records[].data.name:string`) and nothing else — no values, no file contents, no record data. The hash is the point: two failures in a row with the same hash mean the error message did not tell you enough to fix the call, which is how bad errors get found. This turns "this command failed" into "this command failed after these eleven, and the agent never recovered."
+
+Unset, nothing is stored, nothing is sent, and no spool file is created.
+
 In an app project, `lotics app *` commands derive the credential from the directory when nothing explicit chose one: the manifest names the app's workspace, and when exactly one saved profile owns that workspace, that profile is used — the machine-wide default (which another shell can move between two of your commands) is never consulted. An explicit flag, env var, or directory pin still wins, and an org whose profile remembers a different workspace simply falls through to the announced default, exactly as before.
 
 ## Workspaces