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

{solwyn_cli-0.2.0 → solwyn_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: solwyn-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Command-line client for Solwyn
 Author-email: Solwyn <hello@solwyn.ai>
 License-Expression: Apache-2.0
@@ -21,17 +21,22 @@ Description-Content-Type: text/markdown
 
 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.
+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
 
-Until the first release, install from a local checkout:
+Install the published package with uv:
 
 ```console
-uv tool install .
+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
@@ -53,11 +58,19 @@ Calls made through the Solwyn Python SDK are enforced and attributed automatical
 `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 --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
@@ -100,11 +113,15 @@ Every command's `--help` states its exit codes, authentication requirements, and
 | 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).
+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
 
-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.
+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-0.2.0 → solwyn_cli-0.3.0}/README.md

@@ -2,17 +2,22 @@
 
 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.
+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
 
-Until the first release, install from a local checkout:
+Install the published package with uv:
 
 ```console
-uv tool install .
+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
@@ -34,11 +39,19 @@ Calls made through the Solwyn Python SDK are enforced and attributed automatical
 `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 --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
@@ -81,11 +94,15 @@ Every command's `--help` states its exit codes, authentication requirements, and
 | 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).
+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
 
-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.
+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-0.2.0 → solwyn_cli-0.3.0}/docs/caller-owned-spend.md

@@ -27,6 +27,36 @@ replays succeed, while rejections and legacy timestamp collisions exit 1. On an
 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
@@ -63,8 +93,21 @@ either a nullable `result`, or `error_code` and `error_message`. Unknown models
 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.
+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)

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.0 → 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.

solwyn_cli-0.3.0/docs/commands/audit.mdx

@@ -0,0 +1,45 @@
+---
+title: Account audit trail
+---
+
+Read account-wide audit events with JWT; no selected project is required.
+`--range` accepts 7d, 30d (default), 90d or 365d. `--action` matches an exact
+string, not a prefix or wildcard. `--all` follows remaining cursor pages and can
+start from `--cursor`; without it the command returns a single page.
+
+```sh
+solwyn --json audit --range 30d --all
+solwyn audit --action billing.plan_changed
+```
+
+Audit records include account, team, project, key, billing, channel and phone/
+consent actions. Rule add/remove is not audited; only `budget.updated` is in this trail.
+The trail does not include each rule's firing. Use `alerts list --rule-type` for that event history.
+
+Global `--project`, `--api-url` and output flags precede the command.
+Use `--json` for the schema named below unless the command emits plain text.
+
+## `solwyn audit`
+
+List account audit events newest first.
+
+```console
+Usage: solwyn audit [OPTIONS]
+```
+
+| Argument or option | Meaning | Default |
+| --- | --- | --- |
+| `--range` | `Audit window. (Choice(['7d', '30d', '90d', '365d']))` | `30d` |
+| `--action` | `Exact audit action to match. (STRING)` | `None` |
+| `--cursor` | `Opaque cursor from the preceding page. (STRING)` | `None` |
+| `--all` | `Follow cursors until all remaining events are read. (BOOL)` | `False` |
+
+```text
+Endpoint: GET /api/v1/account/audit-events
+Auth: JWT
+Exit codes: 0 success; 1 generic/API; 2 usage; 3 auth
+JSON schema: solwyn.audit.v1
+Actions are exact-match strings; use --all to follow every returned cursor.
+Known actions: account.created, account.updated, team.member_removed, team.member_role_changed, team.invitation_created, team.invitation_revoked, project.created, project.updated, project.archived, budget.defaults_restored, budget.updated, api_key.rotated, api_key.deleted, agent_run.stopped, billing.plan_intent_deleted, billing.plan_changed, billing.cancel_scheduled, billing.cancel_undone, billing.plan_change_discarded, notification_channel.created, notification_channel.updated, notification_channel.deleted, account_phone.verified, account_phone.deleted, consent.sms_alerts_changed, upserted.
+Rule add/remove is not audited; only budget.updated is in this trail. Use alerts list --rule-type for per-rule lifecycle events.
+```

solwyn_cli-0.3.0/docs/commands/budget.mdx

@@ -0,0 +1,20 @@
+# Budget advisory traffic
+
+```sh
+solwyn --project PROJECT budget uncounted
+solwyn --json --project PROJECT budget uncounted
+```
+
+`budget uncounted` reads the separate project resource using JWT or a project key,
+with `solwyn.budget.uncounted.v1`. Calls and tokens are cumulative advisory
+**unpriced upper bounds**, possibly overcounted by at-least-once reporting; they
+are never priced spend, current usage or authoritative billing totals.
+`last_reported_at` is null if the project has never reported. A proven zero is
+zero. A 503 leaves the tally unknown with retry guidance, never a zero tally or
+proof that no traffic occurred. Eligible GETs retain the shared bounded
+Retry-After policy. Existing budget/status reads do not depend on this endpoint.
+MCP provides `budget_uncounted` in both profiles.
+
+`budget rules list --with-last-fired` requires JWT and maps every fetched rule to
+its latest retained fired event or null, preserving percent matching after edits.
+See [alerts](alerts.mdx) for last-firing and pagination semantics.

solwyn_cli-0.3.0/docs/commands/channels.mdx

@@ -0,0 +1,177 @@
+---
+title: Notification channels
+---
+
+Channels belong to the account. Reads require JWT; create/update/test/delete require owner JWT. Integrations
+require Production or above. Supported types are Slack, PagerDuty, Teams,
+Discord and Telegram. Secret input comes from stdin or `SOLWYN_CHANNEL_SECRET`,
+never secret arguments. `--config-stdin` reads a type-specific JSON object.
+List/show responses mask integration secrets.
+
+```sh
+solwyn channels list
+solwyn channels show CHANNEL_ID
+```
+
+Create/update require the type's documented configuration. Slack supports a
+webhook or bot token plus destination; PagerDuty uses a routing key;
+Teams/Discord use webhooks; Telegram uses bot token plus chat id. Test sends a
+real delivery; delete removes the channel and its project notification and
+budget-rule routing references throughout the authenticated account. Delete
+shows the channel identifier and account scope before interactive confirmation
+or `--yes`. Non-TTY without `--yes` exits 2 (`confirmation_required`) before
+credentials or HTTP; decline, EOF or Ctrl-C exits 2 (`confirmation_declined`)
+without mutation. Effects, prompt and echo use sanitized stderr; stdout keeps
+the existing success schema.
+
+```sh
+solwyn channels delete CHANNEL_ID --yes
+```
+
+Global `--project`, `--api-url` and output flags precede the command.
+Use `--json` for the schema named below unless the command emits plain text.
+
+## `solwyn channels`
+
+Manage reusable account notification channels.
+
+```console
+Usage: solwyn channels [OPTIONS] COMMAND [ARGS]...
+```
+
+```text
+Endpoint: composite router for channels subcommands
+Auth: varies by subcommand
+Exit codes: 0 success; 2 usage
+JSON schema: varies by subcommand
+```
+
+## `solwyn channels create`
+
+Create an owner-managed channel using stdin or environment credentials.
+
+```console
+Usage: solwyn channels create [OPTIONS]
+```
+
+| Argument or option | Meaning | Default |
+| --- | --- | --- |
+| `--type` | ` (Choice(['slack', 'pagerduty', 'teams', 'discord', 'telegram']); required)` | `None` |
+| `--name` | ` (STRING; required)` | `None` |
+| `--secret-stdin` | ` (BOOL)` | `False` |
+| `--config-stdin` | `Read the type-specific config JSON object from stdin, including any optional secrets. (BOOL)` | `False` |
+| `--secret-field` | `Secret field name only; defaults to the type's primary secret. (STRING)` | `None` |
+| `--channel` | `Slack destination ID for bot-token mode. (STRING)` | `None` |
+| `--chat-id` | `Telegram destination ID. (STRING)` | `None` |
+
+```text
+Endpoint: POST /api/v1/account/notification-channels
+Auth: JWT; owner for mutations
+Exit codes: 0 success; 1 generic/API or delivery failure; 2 usage; 3 auth; 5 not found
+JSON schema: solwyn.channels.v1
+Secrets only through --secret-stdin, --config-stdin JSON, or SOLWYN_CHANNEL_SECRET; never command arguments.
+Slack requires webhook_url or bot_token + channel; PagerDuty routing_key; Teams/Discord webhook_url; Telegram bot_token + chat_id. All types require Production+.
+```
+
+## `solwyn channels delete`
+
+Delete a channel and remove its project and rule routing references.
+
+```console
+Usage: solwyn channels delete [OPTIONS] CHANNEL_ID
+```
+
+| Argument or option | Meaning | Default |
+| --- | --- | --- |
+| `channel_id` | ` (STRING; required)` | `None` |
+| `--yes` | `Acknowledge the displayed effects without prompting. (BOOL)` | `False` |
+
+```text
+Endpoint: DELETE /api/v1/account/notification-channels/{channel_id}
+Auth: JWT; owner for mutations
+Exit codes: 0 success; 1 generic/API or delivery failure; 2 usage or confirmation; 3 auth; 5 not found
+JSON schema: solwyn.channels.delete.v1
+Effects are shown before interactive confirmation or --yes; non-TTY requires --yes.
+Core removes the channel ID from project notification settings and every budget rule's channel_ids.
+```
+
+## `solwyn channels list`
+
+List account channels with masked credentials.
+
+```console
+Usage: solwyn channels list [OPTIONS]
+```
+
+```text
+Endpoint: GET /api/v1/account/notification-channels
+Auth: JWT
+Exit codes: 0 success; 1 generic/API or delivery failure; 2 usage; 3 auth; 5 not found
+JSON schema: solwyn.channels.list.v1
+```
+
+## `solwyn channels show`
+
+Show a channel; secret fields retain only their final four characters.
+
+```console
+Usage: solwyn channels show [OPTIONS] CHANNEL_ID
+```
+
+| Argument or option | Meaning | Default |
+| --- | --- | --- |
+| `channel_id` | ` (STRING; required)` | `None` |
+
+```text
+Endpoint: GET /api/v1/account/notification-channels/{channel_id}
+Auth: JWT
+Exit codes: 0 success; 1 generic/API or delivery failure; 2 usage; 3 auth; 5 not found
+JSON schema: solwyn.channels.v1
+```
+
+## `solwyn channels test`
+
+Send a test through a stored channel (owner only).
+
+```console
+Usage: solwyn channels test [OPTIONS] CHANNEL_ID
+```
+
+| Argument or option | Meaning | Default |
+| --- | --- | --- |
+| `channel_id` | ` (STRING; required)` | `None` |
+
+```text
+Endpoint: POST /api/v1/account/notification-channels/{channel_id}/test
+Auth: JWT; owner for mutations
+Exit codes: 0 success; 1 generic/API or delivery failure; 2 usage; 3 auth; 5 not found
+JSON schema: solwyn.channels.test.v1
+Sends a real test using the channel's stored credentials. In-band success:false exits 1.
+```
+
+## `solwyn channels update`
+
+Update selected fields; Core retains masked secret values on write-back.
+
+```console
+Usage: solwyn channels update [OPTIONS] CHANNEL_ID
+```
+
+| Argument or option | Meaning | Default |
+| --- | --- | --- |
+| `channel_id` | ` (STRING; required)` | `None` |
+| `--name` | ` (STRING)` | `None` |
+| `--secret-stdin` | ` (BOOL)` | `False` |
+| `--config-stdin` | ` (BOOL)` | `False` |
+| `--secret-field` | ` (STRING)` | `None` |
+| `--channel` | ` (STRING)` | `None` |
+| `--chat-id` | ` (STRING)` | `None` |
+
+```text
+Endpoint: GET then PUT /api/v1/account/notification-channels/{channel_id}
+Auth: JWT; owner for mutations
+Exit codes: 0 success; 1 generic/API or delivery failure; 2 usage; 3 auth; 5 not found
+JSON schema: solwyn.channels.v1
+Secrets only through --secret-stdin, --config-stdin JSON, or SOLWYN_CHANNEL_SECRET; never command arguments.
+Omitted values stay unchanged. Masked secrets retain stored credentials. JSON null clears individual config fields only if the channel remains usable. Type is immutable.
+```