@samva/cli 0.21.0 → 0.22.1

package/AGENTS.md

@@ -1,6 +1,8 @@
 # Samva CLI consumer guide
 
-Use `samva --help` and `samva <command> --help` as the command contract. For automation, prefer
+Use `samva --help` and `samva <command> --help` as the command contract. `--help --json` (or
+`--jsonl`) prints that contract as one result envelope: `data` carries `description`, `usage`,
+`flags`, `globalFlags`, `args`, `subcommands`, and `examples`. For automation, prefer
 `SAMVA_API_KEY`, `--json` for one bounded result, and `--jsonl` with `--all` for streamed lists.
 Machine-readable results go to stdout; warnings and typed errors go to stderr. Error envelopes carry
 `schemaVersion`, `type`, `command`, `reason`, `message`, and optional `next`. For API failures,
@@ -60,7 +62,10 @@ The developer loop for a template project is `samva templates dev` (the local vi
 `vite.config.ts`), `check` (type-check, compile, and render every fixture), `render <template>
 --fixture <name>` (subject, preheader, and plain-text body; `--format html`, `--channel sms|whatsapp`),
 and `snapshot <template> --fixture <name>` (desktop and mobile PNGs, light and dark, in
-`.samva/snapshots`, needing `playwright` in the project or a system Chrome). With `--json`, every
+`.samva/snapshots`, needing `playwright` in the project or a system Chrome; imported images come
+from the project's own files unless an HTTPS `--asset-base` is given). The commands run the project's
+installed `@samva/markup` and `@samva/vite`, which must be on the release line the CLI drives; any
+other line stops with the `npm install` command that fixes it. With `--json`, every
 finding carries `code`, `severity`, `message`, `file`, `line`/`column`, `range`, and, where the
 compiler has them, `fix`, a machine-applicable `edit`, and `upgrade`, the instructions for migrating
 a template written in a format the compiler rejects. Templates live in `templates/` and
@@ -94,7 +99,8 @@ and finish it in the other; `add-asset` alone has no MCP twin, because a chat cl
 bytes to send. Every subcommand prints its complete
 result as JSON because these outputs — revisions, digests, diagnostics — are inputs to the next
 call. `open` returns the revision every other subcommand is fenced to; a workspace that moved refuses
-them, and reopening is the recovery. A source that does not build is a successful call carrying a
+them, and reopening is the recovery. The reads (`diff`, `check`, `fixture`) fence to the current
+revision when `--revision` is omitted. A source that does not build is a successful call carrying a
 null declaration and located findings, not a failed one. `add-asset <template-id> <file>` writes one
 image or font as unsaved bytes at `assets/<file name>` unless `--path` names another project path;
 `--replace` is required to change a path that already holds a file. The Git commands remain the way
@@ -110,7 +116,11 @@ CSS of the brand `--brand <slug>` names, or of the default brand. `--dry-run` va
 catalog: the input each published template accepts, and the reference a send carries. The default
 reference is each template's current publication, so a generated file keeps sending the same
 message until it is regenerated; `--reference contract-latest` follows new publications while the
-input contract holds. `--check` writes nothing and exits `1` when the file no longer describes the
+input contract holds. `--by slug` writes the helper for callers that send by template slug: it
+returns `{ templateSlug, templateData }`, renders the template's current publication (the API takes a
+publication or contract reference only beside a template id), types the input from the current input
+contract, and refuses `--reference`. Both modes export `TemplateSlug`, and `templateData` is typed to
+what `email.send` accepts. `--check` writes nothing and exits `1` when the file no longer describes the
 catalog, naming what moved. A schema the generator cannot express as a checking type is refused
 with the template and the JSON pointer rather than generated as `unknown`.