ynab-api-cli 0.1.0__py3-none-any.whl

ynab_api_cli/resources/skill/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: ynab-api-cli
+description: Use the YNAB API CLI to inspect plans, accounts, categories, transactions, scheduled transactions, and other REST API resources; configure a connection or perform explicitly requested changes.
+---
+
+# YNAB API CLI
+
+Use `ynab-api-cli`, the REST-only CLI distributed with this skill. YNAB calls budgets **plans** in the current API.
+
+- Resolve the installed executable with `ynab-api-cli --help`. For a source checkout, use `uv run --project <project> ynab-api-cli`.
+- On first use in a session, run `doctor`. If configuration is missing, read [references/setup.md](references/setup.md) and give the user the hidden local token-prompt command. Never request a token in chat.
+- `discover`, `discover GROUP`, and `inspect OPERATION_ID` require no connection and make no API requests. Inspect only the operation needed; its output includes only reachable schemas.
+- Use resource commands for ordinary operations or `call OPERATION_ID --request @file` for a JSON envelope containing `path`, `query`, and optional `body`.
+- Prefer explicit UUIDs. A configured default plan is supplied only when plan_id is omitted. Resolve duplicate names through IDs; never infer selection from list position.
+- Read [references/operations.md](references/operations.md) for milliunits, request examples, delta responses, splits, and transfers.
+- Read affected records before an authorized change. Writes preview by default; review target IDs and the exact payload, then use `--execute` within the user's authorization. Existing authorization is sufficient.
+- Verify submitted changes through subsequent reads. After ambiguous failures, inspect state before retrying; the CLI never retries automatically.
+- `compat check` reports upstream contract drift. It does not change the installed CLI or grant permission to adopt new operations.
+- Output is JSON; errors go to stderr. Report exact records and any incomplete verification.
+
+Export this bundled skill with `ynab-api-cli skill export <new-directory>`. This skill is supplementary; the CLI works independently of Codex.

ynab_api_cli/resources/skill/references/operations.md

@@ -0,0 +1,36 @@
+# Operation conventions
+
+```text
+ynab-api-cli discover transactions
+ynab-api-cli inspect getTransactions
+ynab-api-cli transactions get-transactions --plan-id UUID --since-date 2026-01-01
+ynab-api-cli call getTransactions --request @request.json
+```
+
+The equivalent uniform request is:
+
+```json
+{"path":{"plan_id":"UUID"},"query":{"since_date":"2026-01-01"}}
+```
+
+- Amounts are integer milliunits: 12.34 currency units becomes 12340. Expenses are negative. Preserve the plan's currency.
+- Dates follow the inspected ISO schema. Booleans use `true` or `false`; cleared status uses its declared enum.
+- An omitted field differs from explicit null. Never replace unspecified fields with null during an update.
+- Preserve server_knowledge and deleted records when intentionally processing delta responses. The CLI does not maintain synchronization state.
+- Splits and transfers affect linked records. Inspect their models before editing them.
+- Transaction creation accepts exactly one of `transaction` or `transactions`. Direct Import is a separate mutation from creating transactions with import_id.
+
+Create an authorized expense using a body file:
+
+```json
+{"transaction":{"account_id":"ACCOUNT_UUID","date":"2026-01-01","amount":-12340,"category_id":"CATEGORY_UUID","memo":"Authorized expense","approved":false}}
+```
+
+```text
+ynab-api-cli transactions create-transaction --plan-id PLAN_UUID --body @expense.json
+ynab-api-cli transactions create-transaction --plan-id PLAN_UUID --body @expense.json --execute
+```
+
+The first command previews without contacting YNAB. The second submits once. Read the returned transaction ID using get-transaction-by-id to verify the result.
+
+`--metadata` adds HTTP status, relevant headers, and contract version. Unknown parameters and invalid schemas fail before networking; properties allowed by the contract are retained. [Official API conventions](https://api.ynab.com/#data-formats).

ynab_api_cli/resources/skill/references/setup.md

@@ -0,0 +1,32 @@
+# Connection setup
+
+1. Install the CLI from a release wheel or source checkout using `uv tool install <wheel-or-project-path>`.
+2. Open [YNAB Developer Settings](https://app.ynab.com/settings/developer) and generate a personal access token for your own account. [Authentication documentation](https://api.ynab.com/#personal-access-tokens).
+3. In a local interactive terminal:
+
+   ```text
+   ynab-api-cli configure
+   ynab-api-cli doctor
+   ynab-api-cli plans get-plans
+   ynab-api-cli select-plan EXPLICIT_PLAN_UUID
+   ynab-api-cli doctor
+   ```
+
+Configuration uses `$XDG_CONFIG_HOME/ynab-api-cli` or `~/.config/ynab-api-cli`, including Windows. XDG_CONFIG_HOME must be absolute. `auth.json` holds `access_token`; `config.json` holds the optional `plan_id`. Existing unrelated fields are preserved.
+
+`configure` uses hidden input and protects credentials with POSIX mode 600 or a private current-user Windows ACL. It refuses redirected input and existing credentials. `configure --replace` rotates credentials explicitly. Credentials are plaintext: use a private, local directory and exclude it from source control and shared storage.
+
+`doctor --offline` validates files and protection only; it does not prove authentication. Online doctor reads the user and configured plan. `doctor --upstream` additionally checks the published contract.
+
+| Failure | Action |
+| --- | --- |
+| Missing auth.json | Run configure locally |
+| Permissions/ACL failure | Repair file protection or use configure --replace |
+| HTTP 401 | Replace an invalid or revoked token |
+| HTTP 403 | Check account access and token scope |
+| HTTP 404 on selected plan | List plans and select the correct UUID |
+| HTTP 429 | Stop requests; respect rate-limit guidance |
+| Network failure during a write | Read affected records before any retry |
+| Contract or model mismatch | Run compat check and review the supported version |
+
+OAuth refresh and delegated multi-user authentication are outside this release. Each adopter configures a personal token locally.

ynab_api_cli/security.py

@@ -0,0 +1,83 @@
+"""Protect credentials with private POSIX permissions or Windows ACLs."""
+
+from __future__ import annotations
+
+import base64
+import os
+import subprocess
+from pathlib import Path
+
+from ynab_api_cli.exceptions import AppError
+
+
+class FileSecurity:
+    """Apply and inspect credential protection without revealing file contents."""
+
+    def __init__(self, platform: str = os.name) -> None:
+        self.platform = platform
+
+    def powershell(self, script: str) -> str:
+        """Execute a fixed ACL script with no profile or interactive window."""
+        encoded = base64.b64encode(script.encode("utf-16-le")).decode("ascii")
+        try:
+            result = subprocess.run(  # noqa: S603 - encoded fixed ACL script; no shell.
+                [
+                    str(
+                        Path(os.environ.get("SYSTEMROOT", "C:/Windows"))
+                        / "System32/WindowsPowerShell/v1.0/powershell.exe"
+                    ),
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-EncodedCommand",
+                    encoded,
+                ],
+                capture_output=True,
+                text=True,
+                check=True,
+                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+            )
+        except (OSError, subprocess.CalledProcessError) as err:
+            raise AppError(
+                "Cannot inspect or protect Windows credential ACLs."
+            ) from err
+        return result.stdout.strip()
+
+    def protect(self, path: Path) -> None:
+        """Replace permissions on a newly created credential file."""
+        if self.platform != "nt":
+            path.chmod(0o600)
+            return
+        literal = str(path).replace("'", "''")
+        self.powershell(
+            "$ErrorActionPreference='Stop'; "
+            "$sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User; "
+            "$acl=New-Object System.Security.AccessControl.FileSecurity; "
+            "$acl.SetOwner($sid); $acl.SetAccessRuleProtection($true,$false); "
+            "$rule=New-Object System.Security.AccessControl.FileSystemAccessRule"
+            "($sid,'FullControl','Allow'); "
+            "$acl.AddAccessRule($rule); "
+            f"[System.IO.File]::SetAccessControl('{literal}', $acl)"
+        )
+
+    def validate(self, path: Path) -> None:
+        """Refuse credential files readable by other principals."""
+        if self.platform != "nt":
+            if path.stat().st_mode & 0o077:
+                raise AppError("Credential file must have mode 600.")
+            return
+        literal = str(path).replace("'", "''")
+        result = self.powershell(
+            "$ErrorActionPreference='Stop'; "
+            "$sid=[System.Security.Principal.WindowsIdentity]::GetCurrent()"
+            ".User.Value; "
+            f"$acl=[System.IO.File]::GetAccessControl('{literal}'); "
+            "$bad=@($acl.Access | Where-Object { "
+            "$_.AccessControlType -eq 'Allow' -and $_.IdentityReference.Translate"
+            "([System.Security.Principal.SecurityIdentifier]).Value -ne $sid }); "
+            "if ($bad.Count -eq 0 -and $acl.AreAccessRulesProtected) "
+            "{ 'private' } else { 'shared' }"
+        )
+        if result != "private":
+            raise AppError(
+                "Credential ACL is not private; rerun configure --replace locally."
+            )

ynab_api_cli/transport.py

@@ -0,0 +1,133 @@
+"""Bounded REST execution with independent schema checks and raw JSON."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from http import HTTPStatus
+from urllib.parse import quote
+
+import httpx
+
+from ynab_api_cli.contract import Contract
+from ynab_api_cli.exceptions import AppError
+from ynab_api_cli.types import JsonCodec, RequestValues, Response
+
+
+@dataclass(frozen=True, slots=True)
+class Connection:
+    """Connection settings whose token is never included in representations."""
+
+    token: str = field(repr=False)
+    plan_id: str | None = None
+
+    def __post_init__(self) -> None:
+        """Reject invalid header characters without including token contents."""
+        if (
+            not self.token
+            or not self.token.isascii()
+            or not self.token.isprintable()
+            or any(character.isspace() for character in self.token)
+        ):
+            raise AppError("Access token must use visible ASCII without whitespace.")
+
+
+class Transport:
+    """Submit exactly one request; forbid credentials following redirects."""
+
+    BASE_URL = "https://api.ynab.com/v1"
+
+    def __init__(
+        self,
+        connection: Connection,
+        contract: Contract | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.connection = connection
+        self.contract = contract if contract is not None else Contract()
+        self.client = client
+
+    def send(self, identifier: str, request: RequestValues) -> Response[None]:
+        """Validate, serialize, send once, and validate the response JSON."""
+        operation = self.contract.get(identifier)
+        self.contract.validate_request(operation, request)
+        values = request.json()
+        path = operation.path
+        for name, value in self.contract.object(values["path"]).items():
+            path = path.replace("{" + name + "}", quote(str(value), safe=""))
+        query = {
+            key: self.query_value(value)
+            for key, value in self.contract.object(values["query"]).items()
+        }
+        body = (
+            json.dumps(values["body"], ensure_ascii=False, allow_nan=False).encode(
+                "utf-8"
+            )
+            if "body" in values
+            else None
+        )
+        headers = {
+            "Authorization": "Bearer " + self.connection.token,
+            "Accept": "application/json",
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        try:
+            if self.client is not None:
+                response = self.client.request(
+                    operation.method,
+                    self.BASE_URL + path,
+                    params=query,
+                    content=body,
+                    headers=headers,
+                    timeout=30,
+                    follow_redirects=False,
+                )
+            else:
+                with httpx.Client(
+                    verify=True,
+                    follow_redirects=False,
+                    transport=httpx.HTTPTransport(retries=0),
+                    trust_env=False,
+                ) as client:
+                    response = client.request(
+                        operation.method,
+                        self.BASE_URL + path,
+                        params=query,
+                        content=body,
+                        headers=headers,
+                        timeout=30,
+                    )
+        except httpx.HTTPError as err:
+            uncertainty = (
+                " Write outcome may be unknown; inspect state before retrying."
+                if operation.write
+                else ""
+            )
+            raise AppError("YNAB network failure; no retry." + uncertainty) from err
+        if response.status_code >= HTTPStatus.MULTIPLE_CHOICES:
+            retry = response.headers.get("Retry-After")
+            suffix = (
+                f" Retry-After: {retry}."
+                if retry is not None and retry.isdecimal()
+                else ""
+            )
+            raise AppError(f"YNAB HTTP {response.status_code}; no retry." + suffix)
+        try:
+            raw = JsonCodec.loads(response.text)
+        except ValueError as err:
+            raise AppError(
+                "YNAB returned malformed JSON; outcome may be unknown."
+            ) from err
+        self.contract.validate_response(operation, response.status_code, raw)
+        relevant = {
+            key: value
+            for key, value in response.headers.items()
+            if key.lower() in {"content-type", "x-rate-limit", "retry-after"}
+        }
+        return Response(response.status_code, raw, relevant, None)
+
+    @staticmethod
+    def query_value(value: object) -> str:
+        """Encode boolean query values in their lowercase wire form."""
+        return str(value).lower() if isinstance(value, bool) else str(value)

ynab_api_cli/types.py

@@ -0,0 +1,110 @@
+"""Shared JSON values and typed REST requests and responses."""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import date
+from enum import Enum
+from typing import NoReturn, TypeVar, cast
+from uuid import UUID
+
+from pydantic import BaseModel, GetCoreSchemaHandler, TypeAdapter
+from pydantic_core import CoreSchema, core_schema
+
+type JsonValue = (
+    bool | int | float | str | list[JsonValue] | dict[str, JsonValue] | None
+)
+T = TypeVar("T")
+
+
+class Unset:
+    """Distinguish an omitted field from an explicit JSON null."""
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, _source_type: object, _handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        """Require the actual sentinel; never coerce a JSON object into omission."""
+        return core_schema.is_instance_schema(cls)
+
+
+UNSET = Unset()
+
+
+class JsonCodec:
+    """Convert validated Python values without erasing JSON field presence."""
+
+    @classmethod
+    def encode(cls, value: object) -> JsonValue:
+        """Normalize JSON-compatible values and typed contract models."""
+        if isinstance(value, BaseModel):
+            return cls.encode(
+                value.model_dump(mode="python", by_alias=True, exclude_unset=True)
+            )
+        if isinstance(value, dict):
+            return {
+                str(key): cls.encode(item)
+                for key, item in value.items()
+                if not isinstance(item, Unset)
+            }
+        if isinstance(value, (list, tuple)):
+            return [cls.encode(item) for item in value]
+        if isinstance(value, Enum):
+            return cls.encode(value.value)
+        if isinstance(value, (date, UUID)):
+            return value.isoformat() if isinstance(value, date) else str(value)
+        if value is None or isinstance(value, (str, int, float, bool)):
+            if isinstance(value, float) and not math.isfinite(value):
+                raise ValueError("Non-finite numbers are not valid JSON.")
+            return value
+        raise ValueError("Value cannot be represented as JSON.")
+
+    @staticmethod
+    def loads(text: str) -> JsonValue:
+        """Decode JSON into its recursive value type."""
+        # JSON's parser guarantees this recursive union for successfully decoded input.
+        return cast(
+            "JsonValue", json.loads(text, parse_constant=JsonCodec.reject_constant)
+        )
+
+    @staticmethod
+    def reject_constant(_text: str) -> NoReturn:
+        """Reject non-standard JSON numeric constants without exposing values."""
+        raise ValueError("Non-finite numbers are not valid JSON.")
+
+
+@dataclass(frozen=True, slots=True)
+class RequestValues:
+    """Raw or typed endpoint arguments with explicit body presence."""
+
+    path: Mapping[str, object] = field(default_factory=dict)
+    query: Mapping[str, object] = field(default_factory=dict)
+    body: object = UNSET
+
+    def value(self, section: str, name: str, adapter: TypeAdapter[T]) -> T:
+        """Decode one argument using the generated endpoint's exact type."""
+        source = self.path if section == "path" else self.query
+        return adapter.validate_python(source.get(name, UNSET))
+
+    def json(self) -> dict[str, JsonValue]:
+        """Normalize the request without inserting omitted bodies or fields."""
+        values: dict[str, JsonValue] = {
+            "path": JsonCodec.encode(self.path),
+            "query": JsonCodec.encode(self.query),
+        }
+        if not isinstance(self.body, Unset):
+            values["body"] = JsonCodec.encode(self.body)
+        return values
+
+
+@dataclass(frozen=True, slots=True)
+class Response[T_co]:
+    """HTTP response retaining raw JSON, headers, and its typed representation."""
+
+    status: int
+    raw: JsonValue
+    headers: dict[str, str]
+    parsed: T_co

ynab_api_cli/verification.py

@@ -0,0 +1,167 @@
+"""Reviewed feature manifests and public upstream candidate verification."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import yaml
+
+from ynab_api_cli.compat import Compatibility
+from ynab_api_cli.contract import Contract
+from ynab_api_cli.contract_testing import SchemaCases
+from ynab_api_cli.development import Development
+
+
+class Verification:
+    """Keep acceptance manifests reviewed and detect all structural changes."""
+
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = root if root is not None else Path(__file__).resolve().parents[2]
+
+    @classmethod
+    def main(cls) -> None:
+        """Execute the public poe verification tasks."""
+        parser = argparse.ArgumentParser()
+        parser.add_argument(
+            "command",
+            choices=["manifest-init", "contract-check", "compat-check", "skill-check"],
+        )
+        command = str(parser.parse_args().command)
+        instance = cls()
+        if command == "manifest-init":
+            with (
+                instance.root / "src/ynab_api_cli/resources/schema_features.json"
+            ).open("x", encoding="utf-8") as stream:
+                json.dump(instance.manifest(), stream, indent=2)
+                stream.write("\n")
+        elif command == "contract-check":
+            instance.contract_check()
+        elif command == "skill-check":
+            instance.skill_check()
+        else:
+            instance.compat_check()
+
+    @staticmethod
+    def manifest() -> dict[str, str]:
+        """Fingerprint every declared schema node, enum variant, and null branch."""
+        return {
+            probe.identifier: hashlib.sha256(
+                json.dumps(
+                    Compatibility.structural(probe.schema), sort_keys=True
+                ).encode("utf-8")
+            ).hexdigest()
+            for probe in SchemaCases(Contract()).probes()
+        }
+
+    def contract_check(self) -> None:
+        """Require review when any existing or additional schema feature changes."""
+        resource = self.root / "src/ynab_api_cli/resources"
+        reviewed = json.loads(
+            (resource / "schema_features.json").read_text(encoding="utf-8")
+        )
+        if reviewed != self.manifest():
+            raise SystemExit(
+                "Schema feature manifest differs; review all changed cases."
+            )
+        subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "pytest",
+                "tests/test_contract.py",
+                "tests/test_typing.py",
+                "tests/test_features.py",
+                "-q",
+            ],
+            cwd=self.root,
+            check=True,
+        )
+
+    def skill_check(self) -> None:
+        """Ensure canonical and installed skill files match exactly."""
+        canonical = self.root / "skills/ynab-api-cli"
+        bundled = self.root / "src/ynab_api_cli/resources/skill"
+        left = {
+            str(path.relative_to(canonical)): path.read_bytes()
+            for path in canonical.rglob("*")
+            if path.is_file()
+        }
+        right = {
+            str(path.relative_to(bundled)): path.read_bytes()
+            for path in bundled.rglob("*")
+            if path.is_file()
+        }
+        if not left or left != right:
+            raise SystemExit("Canonical and bundled skill resources differ.")
+
+    def compat_check(self) -> None:
+        """Generate, type-check, and test a candidate without editing the checkout."""
+        checker = Compatibility()
+        latest = checker.fetch()
+        report = checker.compare(latest)
+        sys.stdout.write(json.dumps(report, indent=2) + "\n")
+        with tempfile.TemporaryDirectory() as temporary:
+            candidate = Path(temporary) / "candidate"
+            shutil.copytree(
+                self.root,
+                candidate,
+                ignore=shutil.ignore_patterns(
+                    ".git",
+                    ".venv",
+                    ".ruff_cache",
+                    ".pytest_cache",
+                    "__pycache__",
+                    "dist",
+                    ".hypothesis",
+                    ".coverage",
+                ),
+            )
+            spec_path = candidate / "src/ynab_api_cli/resources/openapi.yaml"
+            spec_path.write_text(
+                yaml.safe_dump(latest, sort_keys=False), encoding="utf-8"
+            )
+            Development(candidate).generate(check=False)
+            subprocess.run(  # noqa: S603 - fixed checker module; no shell.
+                [
+                    sys.executable,
+                    "-m",
+                    "ty",
+                    "check",
+                    str(candidate),
+                    "--python",
+                    sys.executable,
+                ],
+                cwd=candidate,
+                check=True,
+            )
+            environment = dict(os.environ)
+            environment["PYTHONPATH"] = str(candidate / "src")
+            subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "pytest",
+                    "tests/test_contract.py",
+                    "tests/test_compat.py",
+                    "tests/test_typing.py",
+                    "tests/test_features.py",
+                    "-q",
+                ],
+                cwd=candidate,
+                env=environment,
+                check=True,
+            )
+        if report["compatible"] is not True:
+            raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    Verification.main()

ynab_api_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.3
+Name: ynab-api-cli
+Version: 0.1.0
+Summary: Complete contract-driven REST CLI for YNAB
+Author: Mike Hill
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: jsonschema[format]>=4.26.0
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/mikejhill/ynab-api-cli
+Project-URL: Repository, https://github.com/mikejhill/ynab-api-cli
+Project-URL: Issues, https://github.com/mikejhill/ynab-api-cli/issues
+Description-Content-Type: text/markdown
+
+# YNAB API CLI
+
+Complete, synchronous REST CLI for the reviewed YNAB API contract. The official SDK is not a dependency. Generated, strictly typed endpoint classes and models are included for Python callers.
+
+## Install and connect
+
+```text
+uv tool install ynab-api-cli
+ynab-api-cli configure
+ynab-api-cli doctor
+ynab-api-cli plans get-plans
+ynab-api-cli select-plan PLAN_UUID
+ynab-api-cli doctor
+```
+
+Generate your personal token in [YNAB Developer Settings](https://app.ynab.com/settings/developer), then enter it through the hidden terminal prompt. Do not put it in command arguments. Configuration is stored under `$XDG_CONFIG_HOME/ynab-api-cli`, falling back to `~/.config/ynab-api-cli` on all platforms. Credentials are plaintext and protected with private POSIX permissions or a current-user Windows ACL.
+
+```text
+ynab-api-cli discover
+ynab-api-cli discover transactions
+ynab-api-cli inspect createTransaction
+ynab-api-cli transactions get-transactions --since-date 2026-01-01
+ynab-api-cli call getTransactions --request @request.json
+```
+
+Uniform requests use `{"path":{},"query":{},"body":{}}`; omit body for operations without one. `--request -` and `--body -` read stdin. Endpoint flags use kebab-case names. Boolean flags take `true` or `false`.
+
+Writes preview by default. Add `--execute` only for an intended mutation and verify its result through reads. Requests use TLS, a 30-second timeout, and no automatic retries or redirects. An uncertain write must be reconciled before retrying. Amounts are integer milliunits, and explicit null differs from omission.
+
+`--metadata` adds status, selected headers, and contract version. Exit codes: 0 success, 1 configuration/API/compatibility failure, 2 usage error, and 130 interruption. `doctor --offline` does not validate API access. `configure --replace` explicitly rotates credentials while preserving unrelated fields.
+
+## Typed Python interface
+
+```python
+from ynab_api_cli.generated.api.transactions.get_transactions import Endpoint
+from ynab_api_cli.transport import Connection, Transport
+
+# Load protected credentials through ConfigStore in real applications.
+response = Endpoint.execute(transport=Transport(Connection(token)), plan_id=plan_id)
+raw_json = response.raw
+typed_result = response.parsed
+```
+
+Typed endpoint execution directly submits mutations; preview guards belong to the CLI. The transport independently validates requests and responses against the bundled contract. Raw JSON remains available alongside typed parsing.
+
+## Development and maintenance
+
+```text
+uv sync --locked
+uv run poe fix
+uv run poe check
+uv run poe codegen-check
+uv run poe contract-check
+uv run poe compat-check
+uv build
+```
+
+The contract snapshot, reviewed operation catalog, and provenance are packaged resources. Generator configuration lives in pyproject.toml; templates and deterministic transforms produce all generated code. Do not edit generated files manually.
+
+See [maintenance](docs/maintenance.md) for reviewed upgrades, test coverage, and CI. See [live testing](docs/live-testing.md) before enabling writes against a dedicated test plan.
+
+## Supplementary Codex skill
+
+```text
+ynab-api-cli skill show
+ynab-api-cli skill export /path/to/codex/skills/ynab-api-cli
+```
+
+Export refuses an existing destination. The canonical skill is in skills/ynab-api-cli and is also included as installed package data. The CLI works independently of Codex.
+
+For a source checkout, install with `uv tool install .` or run commands with `uv run ynab-api-cli`.
+
+## Releases
+
+The publishing pipeline follows VerdiClip's release-please and PyPI trusted-publishing pattern. See [publishing](docs/publishing.md) for the initial project setup, release process, and TestPyPI option.