solwyn-cli 0.2.0rc1__tar.gz → 0.3.0__tar.gz

{solwyn_cli-0.2.0rc1 → solwyn_cli-0.3.0}/CONTRIBUTING.md

@@ -10,6 +10,12 @@ uv run ruff format --check .
 uv run pytest
 ```
 
+For deployed API validation, export a staging account JWT as `SOLWYN_JWT` and run
+`make smoke-cli` or `make smoke-mcp`. Each command creates a disposable project,
+records synthetic durable spend, tests budget enforcement and reporting, and
+archives the project afterward. See [staging smoke tests](docs/staging-smoke.md)
+for prerequisites, coverage, and dashboard inspection options.
+
 ## Command and output contracts
 
 Treat command names, flags, help text, exit codes, stdout/stderr behavior, and JSON schemas as

solwyn_cli-0.3.0/Makefile

@@ -0,0 +1,8 @@
+.PHONY: smoke-cli smoke-mcp
+
+# Creates synthetic durable spend in a disposable staging project; requires SOLWYN_JWT.
+smoke-cli:
+	@uv run --locked python scripts/budget-plane-cli-smoke.py $(SMOKE_ARGS)
+
+smoke-mcp:
+	@uv run --locked python scripts/budget-plane-mcp-smoke.py $(SMOKE_ARGS)

solwyn_cli-0.3.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: solwyn-cli
+Version: 0.3.0
+Summary: Command-line client for Solwyn
+Author-email: Solwyn <hello@solwyn.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25
+Requires-Dist: mcp==2.1.1
+Requires-Dist: platformdirs>=4
+Requires-Dist: pydantic>=2
+Requires-Dist: rich>=13
+Requires-Dist: tomli-w>=1
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# Solwyn CLI
+
+Work with Solwyn from the command line: enforce and attribute LLM spend for calls the Solwyn SDK does not instrument, inspect budgets, costs, and provider health, and recover from leaked or expired project keys — from your terminal, your scripts, or your coding agent.
+
+This README describes solwyn-cli 0.3.0. The package is distributed on PyPI as `solwyn-cli`;
+run `solwyn --version` to see which version you have installed, and use `solwyn --help`
+and MCP discovery to inspect its exact surface.
+
+## Installation
+
+Install the published package with uv:
+
+```console
+uv tool install solwyn-cli
+solwyn --version
+```
+
+Or use `pipx install solwyn-cli`. For development or unreleased commands, install
+from an authorized checkout with `uv tool install .`.
+
+Requires Python 3.11 or newer. The package installs two identical executables: `solwyn` and `solwyn-cli` (an alias matching the package name).
+
+## Getting started
+
+```console
+solwyn login          # authenticate; use --with-key to store a project key instead
+solwyn init           # configure Solwyn for the current repository
+solwyn status         # project budget and provider health at a glance
+```
+
+`solwyn init` authenticates, selects a project, writes local configuration, detects the provider SDKs your code imports, prints the wiring for each, and verifies your budget end-to-end. Add `--agents` to also write guidance files for Claude, Cursor, and `AGENTS.md`.
+
+## Three ways to use it
+
+Calls made through the Solwyn Python SDK are enforced and attributed automatically. The CLI covers the three cases the SDK cannot reach.
+
+### Give a coding agent a budget
+
+`solwyn mcp` serves read, guardrail, and attribution tools to any MCP client over local stdio, resolving configuration and credentials fresh on every call. Standard MCP capability and schema discovery exposes the exact tools and input/output shapes in the running version. `solwyn agent-context` prints a compact SDK 0.6 capability contract suitable for pasting into an agent's context, and `solwyn init --agents` writes the equivalent guidance into the repository.
+
+```console
+solwyn --project proj_0123456789abcdef01234567 mcp --profile read   # 33 read tools
+solwyn --project proj_0123456789abcdef01234567 mcp                  # default guardrails profile, all 37 tools
+solwyn doctor --mcp                                                 # verify the wiring
+```
+
+Customer reads include account-wide alert activity and open deliveries, last firing,
+advisory unpriced outage traffic, plan catalog/status/change preview, identity/email verification,
+phone/SMS prerequisites, team roster/invitations, cost analysis/simulation, provider visibility and audit.
+The 33 reads appear in both profiles; billing/team/member writes remain CLI-only.
+See [alerts](docs/commands/alerts.mdx), [budget](docs/commands/budget.mdx),
+[plan](docs/commands/plan.mdx), [account](docs/commands/account.mdx),
+[team](docs/commands/team.mdx) and [invitation acceptance](docs/commands/invite.mdx).
+
+Start with the [MCP quickstart](docs/mcp-quickstart.md). Profiles are fixed at launch and never grant permissions; see [MCP profiles and tool contracts](docs/mcp-profiles.md) and the [agent integration guide](https://docs.solwyn.ai/docs/cli/agents).
+
+### Gate CI on budget
+
+One pipeline step, one exit code, no code change. `budget status` is a pure read, so a read-only key is enough.
+
+```console
+# Exit 4 when the project is at or over 80% of its monthly budget.
+solwyn --json budget status --max-utilization 80
+```
+
+See [Gate CI on budget](https://docs.solwyn.ai/docs/cli/ci-budget-gate).
+
+### Meter a call the SDK does not wrap
+
+For a `curl`, another language, or a one-off script, reserve budget before the call and settle it after. A denied check exits with code 4, so scripts stop before they spend.
+
+```console
+# 1. Reserve immediately before the call.
+solwyn budget check --provider openai --model gpt-4.1 --estimated-input-tokens 1200
+
+# 2. Make the provider call yourself.
+
+# 3. Settle with what the call actually used. This also records attribution.
+solwyn budget confirm --call-id 12345678-1234-1234-1234-123456789abc --provider openai --model gpt-4.1 \
+  --reservation-id "$RESERVATION" --input-tokens 1180 --output-tokens 640
+```
+
+The CLI's caller-owned workflow maintains parity with Solwyn Python SDK 0.6.0 semantics and covers enforcement and attribution. Use `record` for a completed call that had no reservation, such as a local model. The same loop prices image, video, audio, and speech calls by their billed units, declares fallback intent, scopes enforcement to a single agent run, and reserves for a batch of calls at once; see [Meter un-instrumented calls](https://docs.solwyn.ai/docs/cli/metering-uninstrumented-calls) for the walkthrough and [caller-owned spend reference](docs/caller-owned-spend.md) for the full rules.
+
+## Commands
+
+Every command's `--help` states its exit codes, authentication requirements, and JSON output schema.
+
+| Group | Commands |
+| --- | --- |
+| Setup and identity | `init`, `login`, `logout`, `whoami`, `doctor` |
+| Monitoring | `status`, `costs`, `forecast`, `overview`, `providers` |
+| Budget guardrails | `budget status` / `check` / `confirm` / `set`, `record`, `runs` |
+| Agents | `mcp`, `mcp-config`, `agent-context` |
+| Administration | `budget rules` / `rule` / `threshold`, `alerts`, `channels`, `notifications`, `webhooks`, `keys`, `projects`, `account`, `tags`, `audit`, `attest`, `plan`, `config` |
+
+Account management includes subscription preview, change, cancellation/resume,
+scheduled-change discard, hosted checkout/portal links and pending-intent dismissal.
+Billing writes require owner JWT and confirmation or `--yes`; preview is a JWT
+read at any role. See the [plan reference](docs/commands/plan.mdx). The [in-repo command reference](docs/commands/README.md) describes this checkout.
+The published guide lives in the [CLI docs](https://docs.solwyn.ai/docs/cli).
+
+## Scripting
+
+API and setup commands support global `--json` for schema-bearing JSON output (each payload names its schema, e.g. `solwyn.costs.v1`), and exit codes are stable and documented per command: `0` success, `2` usage, with distinct codes for API, auth, budget-denial, and not-found failures. The local `config` commands emit plain text. Global flags select the project (`--project`), API base URL (`--api-url`), and output format, and go before the subcommand.
+
+## Trust posture
+
+Solwyn CLI:
+
+- sends only your own spend events; `sdk_instance_id` is an invocation ID (the retained operation UUID for recoverable MCP batches); no telemetry;
+- never captures, logs, or transmits prompts or responses;
+- never collects, stores, or proxies provider API keys;
+- has no telemetry, update checks, or phone-home behavior; and
+- stores Solwyn credentials only in the operating system keychain, never in configuration files, command-line arguments, or output.
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) for dependency and environment management.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local workflow and contract-update rules.
+
+```console
+uv sync --locked --all-groups
+uv run solwyn --version
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```
+
+Two test-suite properties worth knowing before contributing:
+
+- Any change to the CLI surface (commands, flags, help text, exit codes, JSON output) requires regenerating the machine-readable contract snapshot with `scripts/generate_contract.py`; `tests/test_contract_snapshot.py` fails until you do.
+- The vendored OpenAPI snapshot and its drift guards are self-invalidating by design — adopt fields properly or record a decline in the registry; never loosen a guard to make a test pass.
+
+The vendored snapshot has two independent safeguards: public CLI CI checks its age and the
+checked-in request/response contracts, while a proposed private monitor compares its content
+with Core. The private monitor, ownership, and verified Core follow-ups are documented in
+[Core contract follow-ups](docs/core-followups.md) and tracked in
+[Core issue #403](https://github.com/solwyn-ai/core/issues/403).
+
+Further in-repo references: [MCP release checklist](docs/mcp-release.md), [bounded MCP work and recovery](docs/mcp-bounded-work.md), [MCP diagnostics](docs/mcp-diagnostics.md), [media confirmation](docs/media-confirmation.md), and [staging smoke tests](docs/staging-smoke.md).
+
+## Security
+
+Please report security issues privately as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+Licensed under the Apache License 2.0. See [LICENSE](LICENSE).

solwyn_cli-0.3.0/README.md

@@ -0,0 +1,149 @@
+# Solwyn CLI
+
+Work with Solwyn from the command line: enforce and attribute LLM spend for calls the Solwyn SDK does not instrument, inspect budgets, costs, and provider health, and recover from leaked or expired project keys — from your terminal, your scripts, or your coding agent.
+
+This README describes solwyn-cli 0.3.0. The package is distributed on PyPI as `solwyn-cli`;
+run `solwyn --version` to see which version you have installed, and use `solwyn --help`
+and MCP discovery to inspect its exact surface.
+
+## Installation
+
+Install the published package with uv:
+
+```console
+uv tool install solwyn-cli
+solwyn --version
+```
+
+Or use `pipx install solwyn-cli`. For development or unreleased commands, install
+from an authorized checkout with `uv tool install .`.
+
+Requires Python 3.11 or newer. The package installs two identical executables: `solwyn` and `solwyn-cli` (an alias matching the package name).
+
+## Getting started
+
+```console
+solwyn login          # authenticate; use --with-key to store a project key instead
+solwyn init           # configure Solwyn for the current repository
+solwyn status         # project budget and provider health at a glance
+```
+
+`solwyn init` authenticates, selects a project, writes local configuration, detects the provider SDKs your code imports, prints the wiring for each, and verifies your budget end-to-end. Add `--agents` to also write guidance files for Claude, Cursor, and `AGENTS.md`.
+
+## Three ways to use it
+
+Calls made through the Solwyn Python SDK are enforced and attributed automatically. The CLI covers the three cases the SDK cannot reach.
+
+### Give a coding agent a budget
+
+`solwyn mcp` serves read, guardrail, and attribution tools to any MCP client over local stdio, resolving configuration and credentials fresh on every call. Standard MCP capability and schema discovery exposes the exact tools and input/output shapes in the running version. `solwyn agent-context` prints a compact SDK 0.6 capability contract suitable for pasting into an agent's context, and `solwyn init --agents` writes the equivalent guidance into the repository.
+
+```console
+solwyn --project proj_0123456789abcdef01234567 mcp --profile read   # 33 read tools
+solwyn --project proj_0123456789abcdef01234567 mcp                  # default guardrails profile, all 37 tools
+solwyn doctor --mcp                                                 # verify the wiring
+```
+
+Customer reads include account-wide alert activity and open deliveries, last firing,
+advisory unpriced outage traffic, plan catalog/status/change preview, identity/email verification,
+phone/SMS prerequisites, team roster/invitations, cost analysis/simulation, provider visibility and audit.
+The 33 reads appear in both profiles; billing/team/member writes remain CLI-only.
+See [alerts](docs/commands/alerts.mdx), [budget](docs/commands/budget.mdx),
+[plan](docs/commands/plan.mdx), [account](docs/commands/account.mdx),
+[team](docs/commands/team.mdx) and [invitation acceptance](docs/commands/invite.mdx).
+
+Start with the [MCP quickstart](docs/mcp-quickstart.md). Profiles are fixed at launch and never grant permissions; see [MCP profiles and tool contracts](docs/mcp-profiles.md) and the [agent integration guide](https://docs.solwyn.ai/docs/cli/agents).
+
+### Gate CI on budget
+
+One pipeline step, one exit code, no code change. `budget status` is a pure read, so a read-only key is enough.
+
+```console
+# Exit 4 when the project is at or over 80% of its monthly budget.
+solwyn --json budget status --max-utilization 80
+```
+
+See [Gate CI on budget](https://docs.solwyn.ai/docs/cli/ci-budget-gate).
+
+### Meter a call the SDK does not wrap
+
+For a `curl`, another language, or a one-off script, reserve budget before the call and settle it after. A denied check exits with code 4, so scripts stop before they spend.
+
+```console
+# 1. Reserve immediately before the call.
+solwyn budget check --provider openai --model gpt-4.1 --estimated-input-tokens 1200
+
+# 2. Make the provider call yourself.
+
+# 3. Settle with what the call actually used. This also records attribution.
+solwyn budget confirm --call-id 12345678-1234-1234-1234-123456789abc --provider openai --model gpt-4.1 \
+  --reservation-id "$RESERVATION" --input-tokens 1180 --output-tokens 640
+```
+
+The CLI's caller-owned workflow maintains parity with Solwyn Python SDK 0.6.0 semantics and covers enforcement and attribution. Use `record` for a completed call that had no reservation, such as a local model. The same loop prices image, video, audio, and speech calls by their billed units, declares fallback intent, scopes enforcement to a single agent run, and reserves for a batch of calls at once; see [Meter un-instrumented calls](https://docs.solwyn.ai/docs/cli/metering-uninstrumented-calls) for the walkthrough and [caller-owned spend reference](docs/caller-owned-spend.md) for the full rules.
+
+## Commands
+
+Every command's `--help` states its exit codes, authentication requirements, and JSON output schema.
+
+| Group | Commands |
+| --- | --- |
+| Setup and identity | `init`, `login`, `logout`, `whoami`, `doctor` |
+| Monitoring | `status`, `costs`, `forecast`, `overview`, `providers` |
+| Budget guardrails | `budget status` / `check` / `confirm` / `set`, `record`, `runs` |
+| Agents | `mcp`, `mcp-config`, `agent-context` |
+| Administration | `budget rules` / `rule` / `threshold`, `alerts`, `channels`, `notifications`, `webhooks`, `keys`, `projects`, `account`, `tags`, `audit`, `attest`, `plan`, `config` |
+
+Account management includes subscription preview, change, cancellation/resume,
+scheduled-change discard, hosted checkout/portal links and pending-intent dismissal.
+Billing writes require owner JWT and confirmation or `--yes`; preview is a JWT
+read at any role. See the [plan reference](docs/commands/plan.mdx). The [in-repo command reference](docs/commands/README.md) describes this checkout.
+The published guide lives in the [CLI docs](https://docs.solwyn.ai/docs/cli).
+
+## Scripting
+
+API and setup commands support global `--json` for schema-bearing JSON output (each payload names its schema, e.g. `solwyn.costs.v1`), and exit codes are stable and documented per command: `0` success, `2` usage, with distinct codes for API, auth, budget-denial, and not-found failures. The local `config` commands emit plain text. Global flags select the project (`--project`), API base URL (`--api-url`), and output format, and go before the subcommand.
+
+## Trust posture
+
+Solwyn CLI:
+
+- sends only your own spend events; `sdk_instance_id` is an invocation ID (the retained operation UUID for recoverable MCP batches); no telemetry;
+- never captures, logs, or transmits prompts or responses;
+- never collects, stores, or proxies provider API keys;
+- has no telemetry, update checks, or phone-home behavior; and
+- stores Solwyn credentials only in the operating system keychain, never in configuration files, command-line arguments, or output.
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) for dependency and environment management.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local workflow and contract-update rules.
+
+```console
+uv sync --locked --all-groups
+uv run solwyn --version
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```
+
+Two test-suite properties worth knowing before contributing:
+
+- Any change to the CLI surface (commands, flags, help text, exit codes, JSON output) requires regenerating the machine-readable contract snapshot with `scripts/generate_contract.py`; `tests/test_contract_snapshot.py` fails until you do.
+- The vendored OpenAPI snapshot and its drift guards are self-invalidating by design — adopt fields properly or record a decline in the registry; never loosen a guard to make a test pass.
+
+The vendored snapshot has two independent safeguards: public CLI CI checks its age and the
+checked-in request/response contracts, while a proposed private monitor compares its content
+with Core. The private monitor, ownership, and verified Core follow-ups are documented in
+[Core contract follow-ups](docs/core-followups.md) and tracked in
+[Core issue #403](https://github.com/solwyn-ai/core/issues/403).
+
+Further in-repo references: [MCP release checklist](docs/mcp-release.md), [bounded MCP work and recovery](docs/mcp-bounded-work.md), [MCP diagnostics](docs/mcp-diagnostics.md), [media confirmation](docs/media-confirmation.md), and [staging smoke tests](docs/staging-smoke.md).
+
+## Security
+
+Please report security issues privately as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+Licensed under the Apache License 2.0. See [LICENSE](LICENSE).

solwyn_cli-0.3.0/docs/caller-owned-spend.md

@@ -0,0 +1,176 @@
+# Caller-owned spend reference
+
+The contract details for attributing, batching, and governing spend the CLI handles
+on the caller's behalf. The [README](../README.md) covers the common case; this page
+holds the full rules for `record`, `budget check --batch`, and budget rules.
+
+## Recording caller-owned spend with `record`
+
+`budget confirm` records attribution after successful settlement by default.
+`--no-record` skips attribution; a recording failure warns without undoing settlement.
+Use `record` for completed calls that have no reservation, including local providers:
+
+```sh
+export SOLWYN_AGENT_RUN_ID="job-42"
+export SOLWYN_TAGS="environment=prod,team=ops"
+solwyn record --provider ollama --model llama3 --input-tokens 120 --output-tokens 30
+solwyn record --batch events.json --json
+solwyn --project YOUR_PROJECT_ID tags list
+```
+
+Reuse the same canonical lowercase `--call-id` UUID for retries of one logical event
+(generate one with `uuidgen | tr A-F a-f`). `record --batch FILE|-` takes a nonempty
+JSON array of event inputs and chunks it into at most 1000 events per request. Each
+invocation uses a fresh `sdk_instance_id` across all its chunks. Never send `cost_usd`
+or `lease_id`; Core computes prices. Inspect `rejected` and `duplicates`: call-ID
+replays succeed, while rejections and legacy timestamp collisions exit 1. On an uncertain
+or partial write, retain the returned `call_ids` in input order before retrying; the
+result has `status=failed` and preserves the dispositions already received.
+
+Core's explicitly unaccepted ingest capacity responses use one of three fixed
+`detail` strings with `Retry-After: 1`: `Budget admission is busy; retry shortly`,
+`Account tag registry is busy; retry the batch.`, or
+`Accounting maintenance is in progress; retry the batch.` These prove that
+individual attempt recorded nothing. The client retries ingest once when any
+`Retry-After` is present, sharing the existing 429 retry budget and 10-second
+wait cap; this replay policy does not itself prove absence.
+If a recognized rejection remains, `record` exits 1 with a retry hint and
+`status=not_recorded` only when no earlier chunk completed and every attempt
+for the failed chunk is provably nonaccepting. Recognized rejections and Core's
+pre-ingest 429/401 responses meet that boundary. An earlier potentially accepted
+attempt stays uncertain even if the final retry is a recognized rejection;
+JWT refresh cannot erase that uncertainty or replenish the shared retry allowance.
+A valid 202 with complete canonical dispositions resolves the call normally.
+A partial multi-chunk invocation retains `status=failed` and all known
+dispositions; the recognized
+rejection proves only the failed chunk was unaccepted if its earlier attempts
+also meet that boundary. A generic/proxy 503, a missing or different header,
+or a transport failure remains uncertain:
+CLI retains `status=failed` and MCP reports `recording=unknown`. Always retry
+attribution with the original `call_ids` and attempt indices.
+
+Budget and quota periods use Core's server receive time (`received_at`), while
+cost analytics use the stored event `timestamp`. A backdated `record --batch`
+event counts against the budget and quota period in which Core receives it,
+but appears on its original day in `costs` if that timestamp is within Core's
+accepted clock bounds. Core clamps excessive future skew and, when a past
+horizon is configured, older timestamps; retention can also hide old analytics.
+Backdating records does not move spend out of the current budget period.
+
+Repeat `--tag key=value` to override environment tags. Keys and values preserve
+whitespace and case; empty values and equals signs in values are legal, commas in
+flag values are not. Tags allow at most 10 keys, keys of 1–64 characters, and values
+up to 256 characters, with no NUL. Reusing `SOLWYN_AGENT_RUN_ID` groups a job's calls;
+otherwise Core creates automatic runs from each invocation's ID.
+
+Denied budget checks also record receipts unless `--no-record` is set. Supply
+`--estimated-output-tokens` to attribute the upper savings bound. Tag submission
+and enforcement work on every tier; discovery is account-scoped and requires Team.
+`tags values KEY --prefix Q` pages through values; retiring a key frees an active
+key slot, and later successful ingest may reactivate it.
+
+## Batch budget checks
+
+`solwyn budget check --batch checks.json --json` reads a nonempty JSON array of
+check bodies; use `--batch -` for stdin. For example:
+
+```json
+[{"model":"gpt-4o","provider":"openai","estimated_input_tokens":1200,"agent_run_id":"job-42","tags":{"environment":"prod"}}]
+```
+
+All bodies validate before submission. Requests contain at most 32 checks, preserve
+input order, and count every item against `checks_per_minute`. Each allowed item
+normally holds its own reservation: confirm it after its provider call. A fail-open
+item has a null reservation and must not be confirmed. Do not poll or repeat checks
+to refresh reservations. Denied items record one receipt each unless `--no-record`
+is set, sharing a fresh invocation ID. `--estimated-output-tokens` applies the same
+savings upper bound to every denial. Put all other per-check options in the JSON;
+missing tags and run IDs inherit `SOLWYN_TAGS` and `SOLWYN_AGENT_RUN_ID`. Explicit
+nulls suppress these defaults. A run ID opts into termination directives.
+
+The `solwyn.budget.check.batch.v1` payload has index-aligned `results`: each contains
+either a nullable `result`, or `error_code` and `error_message`. Unknown models are
+per-item errors. All allowed exits 0, any denial exits 4, and errors without a denial
+exit 1. A request-level 404 or 503 fails the chunk. If an earlier chunk completed,
+its results and reservation IDs remain in output, alongside `failed_chunk_start`
+and `total_checks`; later chunks were not submitted. Every legacy batch 503
+leaves reservation state within the failed chunk unknown, including
+`Budget admission is busy; retry shortly` with `Retry-After: 1`. Core uses that
+same response both before admission and after the legacy loop has committed
+earlier item reservations, so the response cannot distinguish those cases.
+This uncertainty applies even to the first chunk. Do not replay completed
+checks, assume rollback, or blindly resubmit the failed chunk. The CLI does not
+automatically replay budget checks.
+
+For single `/budgets/check` and durable `/budgets/check/batches`, that fixed
+busy detail proves no reservation was made by the request; retrying admission
+in a moment is safe. This is a reservation guarantee: single checks can already
+have folded advisory `uncounted_calls`/`uncounted_tokens` before lock contention.
+A retry can overcount this advisory upper-bound telemetry. Preserve caller
+values; the hint does not promise an absence of all side effects.
+The MCP `budget_check_batch` tool submits at most 32 checks to Core’s durable
+journal with a caller-retained UUIDv7. Recovery uses GET only; explicit denial
+attribution retry preserves its exact event. See [bounded MCP work and recovery](mcp-bounded-work.md)
+for limits, required Core rollout, indexed outcomes and recording uncertainty.
+
+
+## Budget rules and per-run caps
+
+List rule conditions, routing, and separate pause/snooze state:
+
+```sh
+solwyn --project proj_example budget rules list
+solwyn --json --project proj_example budget rules list
+```
+
+Rule mutations require a user login with owner/admin permissions. Each rule may
+reference notification channels with repeatable `--channel ID` options:
+
+```sh
+solwyn budget rule add --type budget_threshold --percent 80
+solwyn budget rule add --type runaway_run --spend 5 --mode hard_deny
+solwyn budget rule add --type scoped_budget --scope tag --match env --value prod --limit 25 --mode hard_deny
+solwyn budget rule add --type forecast_overrun --spend 200
+solwyn budget rule add --type daily_anomaly --multiplier 2 --lookback 7
+solwyn budget rule add --type unit_cost_anomaly --multiplier 3
+```
+
+Runaway `--calls N` and `--window MIN` must be supplied together. Scoped caps also
+accept `--scope model|provider|agent_run`; `--value` is valid only for tag scope.
+The rule count limit includes all six types. Adding a rule preserves the complete
+budget configuration and re-reads it before writing. Core has no concurrency token,
+so this detects changes before the final write but cannot eliminate the remaining
+race. A 503 after a write triggers a read to confirm the complete configuration;
+an unconfirmed outcome requires reviewing the budget before retrying.
+
+```sh
+solwyn budget rule pause RULE_KEY
+solwyn budget rule resume RULE_KEY
+solwyn budget rule snooze RULE_KEY --until +2h
+solwyn budget rule unsnooze RULE_KEY
+solwyn budget rule remove RULE_KEY
+solwyn budget threshold snooze 80 --until 2026-12-01T12:00:00Z
+solwyn budget threshold unsnooze 80
+solwyn budget restore-defaults
+```
+
+Snooze accepts timezone-aware ISO datetimes or `+30m`, `+2h`, and `+1d` durations,
+which the CLI converts to absolute timestamps. **A snoozed hard-deny rule still
+denies; pause releases enforcement.** Rule keys are content-addressed: editing
+keyed condition fields changes the key. Restore-defaults preserves non-threshold
+rules, and the CLI re-reads and prints the full rule state afterward.
+
+Preview routing with a project key or user login, including an unsaved condition:
+
+```sh
+solwyn budget rule preview
+solwyn budget rule preview RULE_KEY --channel CHANNEL_ID
+solwyn budget rule preview --type runaway_run --spend 5 --mode hard_deny
+```
+
+During interactive project creation, `solwyn init --run-cap 5` adds a wildcard
+`runaway_run` rule with `hard_deny` immediately after creation. It caps every run at
+`min(caps)` when run identity is supplied; scoped run caps and wildcard caps share
+the strictest limit. For an existing project, use `budget rule add` instead.
+The default MCP surface includes the pure-read `list_budget_rules` tool; rule
+mutations remain CLI operations.

solwyn_cli-0.3.0/docs/commands/README.md

@@ -0,0 +1,36 @@
+# Command reference
+
+These references describe solwyn-cli 0.3.0. Earlier releases, including 0.2.0, lack many of
+these commands; use installed `--help` and MCP discovery for an installed version's exact surface.
+Global selection/output flags precede commands. Core authorizes every request.
+
+- [Account and identity, rename and recovery](account.mdx)
+- [Alerts](alerts.mdx)
+- [Attest](attest.mdx)
+- [Account audit trail](audit.mdx)
+- [Budget](budget.mdx)
+- [Notification channels](channels.mdx)
+- [Local configuration](config.mdx)
+- [Costs](costs.mdx)
+- [Forecast](forecast.mdx)
+- [Repository setup](init.mdx)
+- [Invitation preview and acceptance](invite.mdx)
+- [Project keys](keys.mdx)
+- [Login and logout](login.mdx)
+- [Project notifications](notifications.mdx)
+- [Overview](overview.mdx)
+- [Plan](plan.mdx)
+- [Projects](projects.mdx)
+- [Provider visibility](providers.mdx)
+- [Agent runs](runs.mdx)
+- [Status](status.mdx)
+- [Tags](tags.mdx)
+- [Team members and invitations](team.mdx)
+- [Webhooks](webhooks.mdx)
+- [Identity](whoami.mdx)
+
+For account settings, see [account rename](account.mdx#rename-the-current-account).
+After membership removal, see [personal-account recovery](account.mdx#recover-a-personal-account).
+
+For caller-owned spend, see [the metering reference](../caller-owned-spend.md).
+For MCP, see [the quickstart](../mcp-quickstart.md).

solwyn_cli-0.3.0/docs/commands/account.mdx

@@ -0,0 +1,59 @@
+# Account and identity reads
+
+```sh
+solwyn whoami
+solwyn --json whoami
+solwyn account phone show
+solwyn --json account phone show
+```
+
+JWT `whoami` shows email verification along with user/account identity, role,
+seats and projects (`solwyn.whoami.v1`). Its strict identity parser adopts
+`email_verified`, first name and marketing email subscription state. Project keys
+return local authentication and selected-project context without inventing a user
+or verified email, and never reveal raw key material. MCP provides `get_whoami`.
+
+`account phone show` (`solwyn.account.phone.v1`) requires JWT and reads the current
+user's state: none, pending, verified or verified_with_pending_change; verified
+and pending numbers, verification/resend timestamps, and SMS consent/disclosure
+state. Verified phone and SMS consent are prerequisites for SMS notifications.
+Absent timestamps remain null. Verification and consent changes stay in the
+dashboard. MCP provides `get_account_phone` in both profiles. Account recovery
+remains CLI-only.
+
+## Rename the current account
+
+```sh
+solwyn account rename "New account name"
+solwyn --json account rename "New account name" --yes
+```
+
+Rename requires owner JWT. It reads the current account and displays its ID,
+old/new names and invitation-email effects before confirmation or `--yes`.
+Non-TTY use without `--yes` exits 2 before reading credentials or HTTP.
+The PATCH sends only `display_name`; `alert_email_override` remains untouched.
+Use the existing `account alert-email show|set|clear` commands to manage that
+independent preference.
+
+Core normalizes display names, rejects controls/bidi/zero-width characters and
+limits them to 120 characters. Invalid input uses fixed errors without reflecting
+validation values. `solwyn.account.rename.v1` returns the complete strict account
+response: ID, display name, tier, alert-email override, seat limit/usage and your
+role. Rename remains CLI-only. Inspect account state before deliberately retrying
+an uncertain write; see [team management](team.mdx).
+
+## Recover a personal account
+
+```sh
+solwyn account recover
+solwyn --json account recover
+```
+
+`account recover` requires JWT but does not require an active membership. It
+idempotently creates a personal account after membership removal, or returns
+the existing account when one is active. The POST goes to
+`/api/v1/accounts/me/personal`; `solwyn.account.recover.v1` returns `account_id`.
+The command stays CLI-only. A project key masking login must be unselected;
+there is no credential fallback. Exit codes are 0 success, 1 API/invalid response,
+2 usage and 3 auth. Core maps a missing user to 401, so there is no not-found
+exit for this route.

{solwyn_cli-0.2.0rc1 → solwyn_cli-0.3.0}/docs/commands/alerts.mdx

@@ -40,4 +40,37 @@ Account configuration uses `solwyn.alerts.account.v1`. Any account member with J
 
 A definite 401 rejection may refresh JWT once; a definite 429 rejection uses the client's bounded rate-limit retry. Mutations are never replayed after 503 or transport failures. If a mutation's outcome is uncertain, inspect `alerts account show` before deciding whether to retry. Role failures exit 3 and point to `whoami`; key authentication failures point to login. Upgrade errors preserve Core's message, allowed values when present, and safe dashboard path. No checkout URL is opened.
 
-The default MCP surface adds only `list_alert_events`, with project/account selection, window and rule filters, cursor/all-pages options, and local failed-only filtering. It exposes the same typed history and receipt fields. Account configuration mutation tools are not registered.
+The MCP surface includes `list_alert_events`, with project/account selection, window and rule filters, cursor/all-pages options, and local failed-only filtering. It exposes the same typed history and receipt fields. Account configuration mutation tools are not registered.
+
+
+```sh
+solwyn alerts activity --range 7d --event-type fired --all
+solwyn alerts activity --cursor CURSOR
+solwyn alerts pending --all
+solwyn --json alerts pending --fail-if-open
+solwyn budget rules list --with-last-fired
+solwyn alerts account show --with-last-fired
+```
+
+Activity is the JWT-only feed across **all projects plus account scope**, unlike
+`alerts list --account`. It supports range 7d/30d/90d (default 30d), event type
+fired/snoozed/unsnoozed/paused/resumed, cursor and all-pages options. Pending reads
+operationally open deliveries without a retention window, with full receipt legs,
+attempt counts and next retry timestamps. Default listing exits 0; `--fail-if-open`
+prints data first then exits 1 with `open_alert_deliveries` and local retry guidance
+when the listed data contains open deliveries. Use `--all` for a complete health
+check. These outputs use `solwyn.alerts.activity.v1` and `solwyn.alerts.pending.v1`.
+
+Last firing is opt-in and requires JWT, including project rules. Selectors come
+from the fetched rules, are chunked at 100, and match thresholds by percent so
+budget-limit edits preserve history. Budget output maps rule keys to firing events
+or null; account output includes last firing and latest lifecycle event, merging
+current account-ID and legacy `account_spend` history by timestamp and event ID.
+Core's
+default 30d window and plan retention apply; null does not prove a rule never
+fired. Without the flag there is no extra request. MCP exposes
+`list_alert_activity`, `list_open_alert_deliveries`, `get_account_alert` and the
+same option on `list_budget_rules`; latest-events POST is a read. No alert
+mutations are exposed. MCP pagination remains bounded, with first unread cursor
+preserved on errors; CLI `--all` fails without printing a false complete result
+if a later page cannot be read.