solwyn-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{solwyn_cli-0.1.0 → solwyn_cli-0.2.0}/.github/workflows/ci.yml

@@ -35,6 +35,10 @@ jobs:
         run: uv run --no-sync ruff check .
       - name: Ruff format check
         run: uv run --no-sync ruff format --check .
+      - name: Validate offline unpublished Registry draft
+        run: uv run --no-sync python scripts/validate_mcp_registry.py
+      - name: Check Python example lock
+        run: uv lock --check --project examples/mcp/python
 
   tests:
     name: Tests (Python ${{ matrix.python-version }})
@@ -57,42 +61,36 @@ jobs:
           version: ${{ env.UV_VERSION }}
       - name: Install dependencies
         run: uv sync --locked --all-groups
+      - name: Install actual legacy MCP client
+        run: |
+          uv venv --python "${{ matrix.python-version }}" "${{ runner.temp }}/mcp-legacy"
+          uv pip sync --python "${{ runner.temp }}/mcp-legacy/bin/python" --require-hashes scripts/locks/mcp-legacy.txt
       - name: Run tests
+        env:
+          SOLWYN_TEST_LEGACY_PYTHON: ${{ runner.temp }}/mcp-legacy/bin/python
         run: uv run --no-sync pytest
 
   packaging-smoke:
-    name: Packaging smoke
-    runs-on: ubuntu-latest
+    name: Wheel MCP (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11"]
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
-          python-version: "3.13"
+          python-version: ${{ matrix.python-version }}
       - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
           version: ${{ env.UV_VERSION }}
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "24"
       - name: Install locked dependencies
         run: uv sync --locked --all-groups
-      - name: Build distributions
-        run: uv build --clear
-      - name: Select exactly one wheel
-        id: wheel
-        run: |
-          shopt -s nullglob
-          wheels=(dist/*.whl)
-          if [[ "${#wheels[@]}" -ne 1 ]]; then
-            echo "expected exactly one wheel, found ${#wheels[@]}" >&2
-            exit 1
-          fi
-          printf 'path=%s\n' "${wheels[0]}" >> "$GITHUB_OUTPUT"
-      - name: Inspect wheel metadata and contents
-        run: uv run --no-sync python scripts/inspect_wheel.py "${{ steps.wheel.outputs.path }}"
-      - name: Test both console entrypoints from the wheel
-        run: |
-          wheel="$(realpath "${{ steps.wheel.outputs.path }}")"
-          smoke_dir="$(mktemp -d)"
-          trap 'rm -rf "$smoke_dir"' EXIT
-          cd "$smoke_dir"
-          UV_CACHE_DIR="$smoke_dir/cache" uvx --from "$wheel" solwyn --version
-          UV_CACHE_DIR="$smoke_dir/cache" uvx --from "$wheel" solwyn-cli --version
+      - name: Run installed-wheel Python, TypeScript, legacy clients and packaged doctor
+        run: uv run --no-sync python scripts/mcp_wheel_smoke.py --python "${{ matrix.python-version }}"

{solwyn_cli-0.1.0 → solwyn_cli-0.2.0}/.github/workflows/publish.yml

@@ -12,7 +12,16 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
-      - uses: hynek/build-and-inspect-python-package@d44ca7d91762de7a7d5436ddae667c6da6d1c3df # v2
+      - id: package
+        uses: hynek/build-and-inspect-python-package@2abe76da66d0a6a4a227101f9348ee855797cfa5 # v3.0.1
+      - name: Verify release tag matches package version
+        env:
+          PACKAGE_VERSION: ${{ steps.package.outputs.package_version }}
+        run: |
+          if [[ "v${PACKAGE_VERSION}" != "${GITHUB_REF_NAME}" ]]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match package version ${PACKAGE_VERSION}. Expected v${PACKAGE_VERSION}."
+            exit 1
+          fi
 
   test:
     name: Test built package
@@ -33,10 +42,10 @@ jobs:
         with:
           name: Packages
           path: dist
-      - name: Install built package and test dependencies
+      - name: Install locked test dependencies
         run: |
-          uv venv --python "${{ matrix.python-version }}"
-          uv pip install --python .venv/bin/python dist/*.whl pytest
+          uv sync --locked --all-groups --no-install-project --python "${{ matrix.python-version }}"
+          uv pip install --python .venv/bin/python --no-deps dist/*.whl
       - name: Test built package
         run: uv run --no-project --python .venv/bin/python pytest tests/ -v --tb=short
 
@@ -55,4 +64,4 @@ jobs:
         with:
           name: Packages
           path: dist
-      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

{solwyn_cli-0.1.0 → solwyn_cli-0.2.0}/.gitignore

@@ -12,3 +12,4 @@ __pycache__/
 dist/
 build/
 *.egg-info/
+.worktrees

solwyn_cli-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to Solwyn CLI
+
+Solwyn CLI uses [uv](https://docs.astral.sh/uv/) for dependency management and command
+execution. Set up a checkout and run the standard verification with:
+
+```console
+uv sync --locked --all-groups
+uv run ruff check .
+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
+public interfaces. When one changes, regenerate the machine-readable CLI contract:
+
+```console
+uv run python scripts/generate_contract.py
+```
+
+Response parsers stay fail-closed. Adopt new Core response fields in the response registry,
+and register every request mirror and every intentionally unadopted optional request field.
+Do not relax a drift guard to make a new Core contract pass.
+
+## OpenAPI snapshot updates
+
+The CLI vendors Core's customer OpenAPI document so normal development, releases, and public
+CI do not need access to the private Core repository. An authorized maintainer updates it from
+a clean Core `main` checkout:
+
+```console
+uv run python scripts/sync_spec.py ../core
+```
+
+The sync records both the UTC date and the exact Core commit. Review the resulting request and
+response drift failures, adopt or explicitly decline every field, regenerate the CLI contract
+when the surface changes, and run the full test suite before committing the snapshot.
+
+Snapshot age and snapshot content answer different questions. The public age check tells us
+how long it has been since a maintainer performed a sync. It cannot determine whether Core's
+contract changed during that time. Content comparison requires a current private Core checkout,
+so it belongs in Core or private infrastructure and must never be added to public CLI CI. See
+[Core contract follow-ups](docs/core-followups.md#private-openapi-content-drift-monitor) for the
+proposed monitor and ownership; implementation is tracked in
+[Core issue #403](https://github.com/solwyn-ai/core/issues/403).
+
+## Pull requests
+
+Keep pull requests focused and include the verification commands and results in the description.
+If the change affects CLI behavior, name the corresponding `solwyn-docs` pages that need an
+update. Do not include credentials, provider payloads, prompts, or responses in fixtures or logs.

solwyn_cli-0.2.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.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: solwyn-cli
+Version: 0.2.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.
+
+> **Status:** pre-release. This repository is private while the first release is prepared, and the package is not yet published to PyPI.
+
+## Installation
+
+Until the first release, install from a local checkout:
+
+```console
+uv tool install .
+solwyn --version
+```
+
+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   # 13 read tools
+solwyn --project proj_0123456789abcdef01234567 mcp                  # default guardrails profile, all 17 tools
+solwyn doctor --mcp                                                 # verify the wiring
+```
+
+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` |
+
+The administration group is for operators and is needed rarely. The full reference for every command lives in the [CLI docs](https://docs.solwyn.ai/docs/cli).
+
+## Scripting
+
+All commands support `--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. 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.2.0/README.md

@@ -0,0 +1,132 @@
+# 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.
+
+> **Status:** pre-release. This repository is private while the first release is prepared, and the package is not yet published to PyPI.
+
+## Installation
+
+Until the first release, install from a local checkout:
+
+```console
+uv tool install .
+solwyn --version
+```
+
+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   # 13 read tools
+solwyn --project proj_0123456789abcdef01234567 mcp                  # default guardrails profile, all 17 tools
+solwyn doctor --mcp                                                 # verify the wiring
+```
+
+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` |
+
+The administration group is for operators and is needed rarely. The full reference for every command lives in the [CLI docs](https://docs.solwyn.ai/docs/cli).
+
+## Scripting
+
+All commands support `--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. 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.2.0/docs/caller-owned-spend.md

@@ -0,0 +1,133 @@
+# 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.
+
+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. Reservation state inside a
+503-failed chunk is unknown. Do not replay completed checks or assume rollback.
+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.2.0/docs/commands/alerts.mdx

@@ -0,0 +1,43 @@
+# Alerts
+
+Inspect alert history, per-channel delivery receipts, and account spend alert configuration.
+
+```sh
+solwyn alerts list --range 7d
+solwyn --json alerts list --rule-type scoped_budget --scope tag --failed-only --all
+solwyn alerts list --cursor CURSOR
+solwyn alerts show EVENT_ID --range 90d
+solwyn alerts list --account --from 2026-09-01T00:00:00Z --to 2026-09-05T00:00:00Z
+```
+
+History defaults to 30 days. Presets are `7d`, `30d`, and `90d`. Custom windows require both timezone-aware bounds with `--to` later than `--from`; these replace the preset. Longer custom windows may require an upgrade. Core clamps retained history and the CLI reports `window.retention_clamped` on stderr. Project history accepts a project key or JWT; account history requires JWT and reads account-scope events.
+
+Core supplies at most 25 events per page and has no `limit` parameter. `--all` walks continuation cursors; otherwise JSON preserves `next_cursor` and table mode prints continuation guidance on stderr. `--scope` matches the rule scope in event metadata, such as `tag`, rather than selecting account versus project history. Scope and rule-type filters allow at most 32 characters and no NUL. `--failed-only` filters the returned page locally to `partial` and `failed` delivery rollups; combine it with `--all` to search all pages. An empty filtered page can still have a continuation cursor.
+
+The delivery column uses Core's worst-leg rollup. `processed` means dispatch was acknowledged without per-channel delivery receipts and does not prove delivery. `partial` means at least one leg succeeded and another failed. JSON includes the full delivery object and legs; leg states can include `accepted`, which differs from parent states. `alerts show` searches the same list endpoint across pages and matches the event ID locally within the selected window. It never calls a nonexistent single-event endpoint. Its table shows channel type/name, status, attempts, delivery time, and error. An event absent from the selected retained window exits 5; a wider window may find it.
+
+List and detail JSON use `solwyn.alerts.v1`. List output carries `events`, `next_cursor`, and `window`; detail output carries the selected event fields. Human notices remain on stderr.
+
+```sh
+solwyn alerts export --format csv > alerts.csv
+solwyn alerts export --account --format json --range 90d > alerts.ndjson
+```
+
+Exports require Production or above (`csv_export` entitlement, including JSON). They stream CSV or newline-delimited JSON bytes to stdout; `--format json` here means NDJSON, without a CLI JSON envelope. Exports exclude `delivery` receipts and do not support list-only scope/rule-type/failed filters. Requested/effective window and retention headers print to stderr. CSV's formula-safety apostrophes and all raw bytes are preserved. A stream failure can leave a partial output file; use a temporary file and rename it only after exit 0. An interrupted response is never replayed automatically.
+
+```sh
+solwyn alerts account show
+solwyn alerts account set --spend 100 --channel CHANNEL_ONE --channel CHANNEL_TWO
+solwyn alerts account set --spend 150 --disabled
+solwyn alerts account snooze --until 2026-09-10T12:00:00Z
+solwyn alerts account snooze --until +2h
+solwyn alerts account unsnooze
+solwyn alerts account preview --channel CHANNEL_ONE
+solwyn alerts account delete
+```
+
+Account configuration uses `solwyn.alerts.account.v1`. Any account member with JWT can show or preview routing. Mutations require the owner, and creating or updating the spend alert requires Production or above (`account_spend_alert`). This is an alert threshold; it does not establish a spend enforcement cap. Spend must be a finite positive USD amount. Repeated `--channel` flags replace the referenced channels. Omitting channels or the enabled toggle preserves existing settings; creation defaults to enabled with no explicit channel refs. Preview is an ungated, side-effect-free POST for an unsaved draft. Snooze takes an absolute timezone-aware timestamp, with relative `+Nm`, `+Nh`, or `+Nd` converted locally. Delete succeeds even if configuration is already absent; show/snooze/unsnooze return exit 5 when absent.
+
+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.