fix(errors): one not-found error, usage tails, limit_reached

[NovusEdge]

Error message and error code QoL, from the human and agent audits.

CLI

• Usage errors print the error, the command's usage line, and a pointer to its --help, not the root help.
• stoat exec --help/-h and stoat help <cmd> (nested too) show that command's help.
• One VM-not-found error with did-you-mean, no internal v2 path; the wrong ~/.stoat/vms wording is gone from code and docs.
• Unknown image id: did-you-mean over catalog ids and local files, plus a pointer to stoat images; the alpine-3.21 example is now alpine-standard.
• cp: no double scp prefix. Confirmation refusal reads 'refusing to delete VM x without confirmation (no terminal); pass -y'.

MCP

• New wire code limit_reached with needed_mb/available_mb; MCP text says to lower ram_mb with update or ask a person. No force parameter added.
• Guard and handler input errors return usage instead of internal.
• Invalid enum values list the valid ones (core wait no longer leaks a Go field name); MCP errors name MCP tools; index-refresh failure keeps stderr; job_kill signal text fixed.
• JSON-schema enums for until, mode, agent_access, stream, action, which. The SDK now rejects a bad value at schema validation, before the handler.
• google/jsonschema-go moves from indirect to direct in go.mod.

Not done: the duplicated error text in MCP results (text block plus JSON envelope). docs/reference/mcp.md documents the second block as the code source for clients that drop _meta, so removing it would break that contract.

Tests: unit only, no VMs booted.

[coderabbitai]

Warning

Review limit reached

Next included review available in 30 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: e506498e-c867-4f6e-ad48-467186fd3a46

📥 Commits

Reviewing files that changed from the base of the PR and between ba413a3 and 46389d1.

📒 Files selected for processing (34)

• docs/reference/json.md
• docs/reference/mcp.md
• docs/reference/project-file.md
• docs/troubleshooting.md
• go.mod
• internal/capabilities/load.go
• internal/cli/cli.go
• internal/cli/cli_test.go
• internal/cli/confirm.go
• internal/cli/grammar.go
• internal/cli/project.go
• internal/cli/project_test.go
• internal/cli/run_recipe_remote.go
• internal/cli/wire/envelope.go
• internal/cli/wire/errors.go
• internal/cli/wire/errors_test.go
• internal/config/config.go
• internal/config/namespace.go
• internal/core/copy.go
• internal/core/image.go
• internal/core/images.go
• internal/core/limits.go
• internal/core/vm.go
• internal/core/wait.go
• internal/coreerr/coreerr.go
• internal/coreerr/coreerr_test.go
• internal/mcpsrv/access.go
• internal/mcpsrv/capabilities_test.go
• internal/mcpsrv/error_contract_test.go
• internal/mcpsrv/guards.go
• internal/mcpsrv/server.go
• internal/mcpsrv/tools_exec.go
• internal/mcpsrv/tools_guest.go
• internal/mcpsrv/tools_recipe.go

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}