@samva/cli 0.5.0 → 0.6.1

package/AGENTS.md

@@ -38,7 +38,7 @@ image or font as unsaved bytes at `assets/<file name>` unless `--path` names ano
 `--replace` is required to change a path that already holds a file. The Git commands remain the way
 to author a project you have cloned.
 
-`samva brands pull [slug]` writes the brand snapshot `.samva/brands/<slug>.json` that `@samva/vite`
+`samva brands pull [slug]` writes the brand snapshot `.samva/brands/<slug>.json` that the CLI
 resolves `samva:brand` from offline; bare `pull` snapshots the default brand, and `theme.css` is
 never written. Keep `.samva` gitignored. `samva brands push <file>` validates brand CSS locally,
 exits `1` with located findings when it is outside the brand grammar, and otherwise replaces the
@@ -57,6 +57,8 @@ repository. `samva templates clone <project-or-template-id>` clones an existing
 repository-local credential helper that exchanges Samva authorization for a short-lived,
 repository-scoped credential; the token is never stored in the remote URL or Git config. Normal
 `git fetch`, `git pull`, `git add`, `git commit`, and `git push` remain the synchronization commands.
+A pushed commit is picked up on the next hosted workspace open; independent draft edits rebase,
+and overlapping edits produce explicit conflicts.
 Install from the project's lockfile (`bun install --frozen-lockfile` or `npm ci`) before `samva templates check` or `samva templates build`, then
 publish a clean, pushed commit with `samva templates publish`. Publish checks that the selected
 commit is an ancestor of the fetched `origin/<default-branch>` and creates an immutable receipt; it
@@ -72,3 +74,7 @@ when it is missing; other CLI commands are self-contained.
 the matching platform-specific `@samva/cli-*` executable and falls back to the packaged JavaScript
 CLI through Bun when npm omits optional dependencies. Depend on `@samva/cli`, never a native
 artifact directly.
+
+Keep Samva brand resolution in the CLI and pass `samvaBrandPlugin` to the project's authoring
+toolchain, so standalone `@samva/vite` stays independent of Samva authentication and storage.
+Standalone callers supply their own resolver. The README owns resolution order and configuration.

package/README.md

@@ -202,8 +202,11 @@ with relative asset URLs, plus `<fixture>.sms.txt` and `<fixture>.whatsapp.json`
 Like `check` and `build`, it treats the current directory as the project: its `theme.css` themes
 the export and `samva:brand` resolves live or from `.samva/brands`.
 
-`git fetch`, `git pull`, `git add`, `git commit`, and `git push` are ordinary Git operations. The
-CLI's `init` and `clone` commands configure the repository-local helper; `publish` does not push
+`git fetch`, `git pull`, `git add`, `git commit`, and `git push` are ordinary Git operations.
+The next hosted workspace open picks up a pushed commit, rebases independent draft edits, and
+records explicit conflicts for overlapping edits.
+
+The CLI's `init` and `clone` commands configure the repository-local helper; `publish` does not push
 for you. It accepts a clean commit that is reachable from the fetched `origin/<default-branch>`
 and publishes that exact commit. A clone records its project in `samva.projectId`; pass
 `--project-id` from a checkout that `samva templates init` or `clone` did not create.
@@ -218,6 +221,14 @@ automation path.
 editor from the project's `@samva/vite/dev` under Node.js, with no `vite.config.ts`. It prints the
 editor URL and runs until interrupted; `SIGINT` and `SIGTERM` close the server.
 
+The CLI supplies Samva brand resolution to `dev`, `check`, `build`, `render`, `snapshot` and
+`export`. An imported `samva:brand` uses `SAMVA_API_KEY` from the environment or project `.env`
+(and `SAMVA_API_URL` for another endpoint), or `samva brands get --json` on `PATH` with your login
+session. Live answers refresh `.samva/brands/<slug>.json`; an unavailable live brand falls back to
+that snapshot with `brand-offline`. A changed live digest reports `brand-snapshot-stale`. With
+neither a live answer nor a snapshot, the command fails with `brand-unavailable`. Keep `.samva/`
+gitignored. Standalone `@samva/vite` callers configure a resolver themselves.
+
 `samva templates check` runs the project's TypeScript configuration, then uses the project's
 `@samva/vite/build` to compile every template, render every fixture, and report located findings
 plus email-client compatibility findings. It writes no files and exits non-zero on TypeScript,