@mechasm/cli 0.1.2 → 0.1.4

package/AGENT_GUIDE.md

@@ -5,11 +5,38 @@ Use Node.js 22 or newer. Install `@mechasm/cli`, sign in with `mechasm login`, t
 Keep each test request in Markdown. Name the project ID, target URL, expected result, and limits. Reuse configured test accounts; do not ask agents to expose credentials or change data outside the named test scope.
 
 ```sh
-mechasm tests create --project PROJECT_ID --name "Sign-in" --prompt-file prompt.md --wait --json
+mechasm tests create --project PROJECT_ID --name "Sign-in" --prompt-file prompt.md --json
 ```
 
-Use explicit project, test, and run IDs. Do not assume a default project. Use `--json` for scripts; stdout contains JSON and errors go to stderr. Save run IDs and log cursors in workflow state. Resume logs with `--after CURSOR` after reconnecting.
+Save the returned `testId`, `runId` and `runUrl`. Follow execution using the run ID:
 
-Exit code `5` means the run failed or was stopped. Code `2` means invalid arguments, `3` authentication failed, and `4` permission was denied. The optional npm update notice runs only in interactive non-JSON sessions; CI skips it.
+```sh
+mechasm runs logs RUN_ID --project PROJECT_ID --follow --json
+```
+
+When the stream finishes, check the final result:
+
+```sh
+mechasm runs status RUN_ID --project PROJECT_ID --json
+```
+
+Log streaming alone does not report pass/fail through its exit code. Do not infer success from a closed stream or an individual log line. For scripts that only need the final result, `--wait` on create/edit/run or `runs wait` waits silently and returns the final result without displaying live logs. With `--json`, it returns one final JSON result.
+
+Let Mechasm's healer work while the run is active. Failed actions, unexpected pages and recovery attempts can be corrected automatically. Wait for the overall run to reach `passed` or `failed`; do not cancel because a few minutes passed or one step failed. Stop when the user requests it, or when you deliberately need to change the prompt before continuing. `runs status` includes `terminal`, the current `progress` phase/start time when available, and safe failure details with a suggested next step. Missing progress is not proof the run is stuck.
+
+Before reporting the outcome, review the logs and available evidence against the user's intended result:
+
+```sh
+mechasm runs trace RUN_ID --project PROJECT_ID --out run-trace.zip
+mechasm runs video RUN_ID --project PROJECT_ID --out run.webm
+```
+
+Check artifact availability in `runs status`; uploads can finish after the run result. Inspect trace screenshots/page snapshots, actions and errors, using video as supporting evidence. Verify that the expected behavior really happened; do not treat an existing file as proof of success. If evidence is unavailable or cannot be opened, report that limit.
+
+If evidence shows a genuine failure of the user's requirement, accept and report the failure. If your prompt introduced an unsupported assumption or was ambiguous, clarify it without weakening the user's requirement, then use `tests edit --prompt-file FILE` and inspect the new run. Ask the user if their intended result is unclear. Do not repeatedly rerun or remove assertions just to get a pass. A manually stopped run proves cancellation, not what the natural result would have been.
+
+Use explicit project, test, and run IDs. Do not assume a default project. Use `--json` for scripts; stdout contains JSON and errors go to stderr. Log following emits JSON lines. Save run IDs and log cursors in workflow state. Resume logs with `--after CURSOR` after reconnecting.
+
+Exit code `5` from a status/get/wait command or a test command using `--wait` means the run failed or was stopped. Code `2` means invalid arguments, `3` authentication failed, and `4` permission was denied. The optional npm update notice runs only in interactive non-JSON sessions; CI skips it.
 
-See [CLI documentation](https://mechasm.ai/docs/mechasm-cli/getting-started) for full command details.
+See [CLI documentation](https://mechasm.ai/docs/mechasm-cli/getting-started) and [agent workflows](https://mechasm.ai/docs/mechasm-cli/agent-workflows) for full command details.

package/README.md

@@ -38,12 +38,24 @@ Pass project IDs explicitly to test, run, variable, and local-app commands. The
 ```sh
 mechasm teams list
 mechasm projects create --name "Store QA" --url https://app.example.com --team TEAM_ID
-mechasm tests create --project PROJECT_ID --name "Home page" --prompt "Open the home page and check that it loads." --wait --json
+mechasm tests create --project PROJECT_ID --name "Home page" --prompt "Open the home page and check that it loads." --json
 ```
 
 Replace `TEAM_ID`, `PROJECT_ID`, and the example URL with your values. `--team` is optional when exactly one team is approved. The project creation response contains the project ID to use in later commands.
 
-Commands that start a run return its `runId` and workspace `runUrl`. `--wait` waits for the final result. Failed or stopped runs exit with code 5.
+Commands that start a run return its `runId` and workspace `runUrl`. Use the returned run ID to follow execution:
+
+```sh
+mechasm runs logs RUN_ID --project PROJECT_ID --follow
+```
+
+After the log stream finishes, check the final result:
+
+```sh
+mechasm runs status RUN_ID --project PROJECT_ID --json
+```
+
+Log streaming alone does not report pass/fail through its exit code. Status/get commands return exit code 5 for failed or stopped runs. For scripts that only need the final result, add the optional `--wait` to create/edit/run, or use `runs wait`. Waiting is silent until completion and does not display live logs. With `--json`, it returns one final JSON result; failed or stopped runs exit with code 5.
 
 ## Manage variables safely
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechasm/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Mechasm command line client",
   "homepage": "https://mechasm.ai/docs/mechasm-cli/getting-started",
   "license": "SEE LICENSE IN LICENSE",

package/src/cli.js

@@ -60,14 +60,19 @@ Options:
   --idempotency-key KEY  Reuse key after an unknown mutation result
   --url URL           Project or local app URL
   --ports LIST        Comma-separated local ports
-  --wait              Wait for test generation or run completion; metadata-only operations return immediately
+  --wait              Wait silently for the final result; metadata-only edits return immediately
   --follow            Follow run logs until it finishes
   --after CURSOR      Resume run log history
   --out FILE          Save video or trace to a new file
   --json              JSON output on stdout; errors on stderr
 
-Commands that start a run return its workspace URL; plain output shows it as "View run".
+Commands that start a run return runId and runUrl; --wait delays output until completion.
+To watch progress, start without --wait, then use: mechasm runs logs RUN_ID --project ID --follow
+After following logs, use runs status to check the result. Log streaming alone does not report pass/fail via its exit code.
 No command opens a local public listener. Project IDs are required for test and run operations.
+
+Documentation: https://mechasm.ai/docs/mechasm-cli/getting-started
+Agent workflows: https://mechasm.ai/docs/mechasm-cli/agent-workflows
 `;
 const RUNNER_MANAGED_VARIABLES = new Set(['CI_TOKEN', 'RUN_WS_TOKEN', 'WS_AUTH_COOKIE']);
 
@@ -176,7 +181,10 @@ function output(value, json) {
     console.log(`Signed in${identity ? ` as ${identity}` : ''}${value.deviceName ? ` (${value.deviceName})` : ''}.`);
   }
   else if (Array.isArray(value?.projects)) {
-    if (!value.projects.length) console.log('No projects available.');
+    if (!value.projects.length) {
+      console.log(value.message || 'No projects available to this device.');
+      if (value.suggestedNextStep) console.log(value.suggestedNextStep);
+    }
     else for (const project of value.projects) console.log(`${project.id}  ${project.name}  ${project.url}`);
   } else if (Array.isArray(value?.tests)) {
     if (!value.tests.length) console.log('No tests found.');