@samva/cli 0.2.0 → 0.3.0

package/AGENTS.md

@@ -17,8 +17,8 @@ each requires `--template-id`, because a reference is a statement about one temp
 
 `samva templates workspace <open|diff|patch|check|fixture|save|history|publish>` is the
 hosted project workspace over the CLI, for a caller with no clone: an agent in a sandbox, a CI job,
-a script. It reaches the same domain-authorized operations the hosted MCP tools reach, so both
-external transports complete one journey against one substrate. Every subcommand prints its complete
+a script. It reaches the same operations the hosted MCP tools reach, so an agent can start a journey in one
+and finish it in the other. 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
@@ -35,26 +35,18 @@ with the template and the JSON pointer rather than generated as `unknown`.
 
 `samva templates init --name <name>` creates a starter-backed Artifact project and clones its Git
 repository. `samva templates clone <template-id>` clones an existing project. Both configure a
-repository-local credential helper that exchanges Samva authorization for a one-hour,
+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.
-Run `bun install --frozen-lockfile` before `samva templates check` or `samva templates build`, then
+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
 does not push or rewrite history. The CLI loads the project's installed authoring toolchain so its
 compiler and editor versions stay pinned by the project lockfile.
-Template authoring commands require Node.js 22 or newer; other CLI commands remain self-contained.
+Template authoring commands run that toolchain under Node.js and name the Node.js version they need
+when it is missing; other CLI commands are self-contained.
 
 `@samva/cli` ships the JavaScript implementation and its runtime dependencies. Its launcher prefers
 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.
-
-## Command handler tracing
-
-Every `Command.withHandler` body uses `Effect.fnUntraced`, and that is the convention for the whole
-command surface rather than an omission at each site. A handler is the process: it runs once, prints,
-and exits, so a span would name the run instead of a step inside it, and the CLI installs no tracer
-to receive one. Reusable work that outlives a single call still carries a name, as
-`src/config/store.ts` does with `Effect.fn("CliConfig.writeConfig")` and
-`Effect.fn("CliConfig.writeCredentials")`.

package/README.md

@@ -63,17 +63,17 @@ the device flow with `samva login --no-browser`; `--no-input`, `--json`, and `--
 If a stored OAuth record is malformed, run `samva logout` and then `samva login`; API-key calls do
 not read or decode stored OAuth credentials.
 
-Profiles hold non-secret target and organization settings. Credentials stay in the OS keyring.
+Profiles hold non-secret organization settings. Credentials stay in the OS keyring.
 
 ```sh
-samva profile create local --target local
-samva profile use local
-samva --profile local email doctor
+samva profile create acme --org acme
+samva profile use acme
+samva --profile acme email doctor
 ```
 
 The profile resolves as `--profile`, then `SAMVA_PROFILE`, then the active profile, then `default`.
-The API URL resolves as `--api-url`, then `SAMVA_API_URL`, then the profile target. `local` targets
-the Portless API origin `https://api.samva.localhost`. `production` targets `https://api.samva.dev`.
+The API URL resolves as `--api-url`, then `SAMVA_API_URL`, then `https://api.samva.dev`. Profiles
+do not select an API; a config whose profile sets `target` fails to load and names these overrides.
 
 ## Common operations
 
@@ -113,6 +113,21 @@ samva email design pull
 samva email design push --dry-run
 ```
 
+## DKIM rotation
+
+Stage a new selector with an explicit retry key:
+
+```sh
+samva email domains rotate-dkim dom_abc123 --idempotency-key rotation-2026-09 --dry-run
+samva email domains rotate-dkim dom_abc123 --idempotency-key rotation-2026-09 --json
+```
+
+Reuse the same key for retries. Publish the returned `record`, then run
+`samva email domains check dom_abc123` to advance verification and cut over.
+Keep `formerRecord` published. `minimumRetainUntil` is only a minimum retention horizon;
+retirement requires separate approval and verification that at least two actual former-record
+TTLs have elapsed. The command never removes DNS records.
+
 ## Template projects
 
 Create a starter-backed project, or clone an existing template project. Samva creates the project
@@ -241,7 +256,7 @@ samva email send --to ada@example.com --subject "Hello" --text "Hi!" --dry-run -
 samva messages list --all --jsonl
 
 # Suppress successful human output.
-samva --quiet profile use local
+samva --quiet profile use acme
 ```
 
 `--json` writes one bounded, versioned result envelope to stdout:
@@ -300,7 +315,7 @@ samva webhooks test wep_abc123 --data '{"event":"webhook.test"}' --json
 samva webhooks test wep_abc123 --data @payload.json --json
 ```
 
-`samva email doctor` reports resolved profile, target, API URL, auth source, organization access,
+`samva email doctor` reports resolved profile, API URL, auth source, organization access,
 sending domains, senders, and domain-verification readback. It is read-only and does not inspect
 receiving configuration, verify DNS, send an email, replay fixtures, or check provider readiness.
 Use `samva email receiving status <domain-id>` to read a domain's receiving prerequisite status.