ynab-api-cli 0.1.0__tar.gz

ynab_api_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: Contract and quality
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      ref:
+        description: Exact revision to validate for a release
+        type: string
+        required: true
+  schedule:
+    - cron: '17 9 * * *'
+permissions:
+  contents: read
+jobs:
+  quality:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          ref: ${{ inputs.ref || github.sha }}
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run poe check
+      - run: uv run poe codegen-check
+      - run: uv run poe contract-check
+      - run: uv run poe skill-check
+      - run: uv build
+      - run: uv run poe distribution-check
+  upstream:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          ref: ${{ inputs.ref || github.sha }}
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: uv sync --locked
+      - run: uv run poe compat-check

ynab_api_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,172 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag to validate and publish (for example v0.1.0)
+        type: string
+        required: true
+      testpypi:
+        description: Publish to TestPyPI instead of PyPI
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: write
+      issues: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+      - name: Validate release pull request
+        if: steps.release.outputs.prs_created == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_JSON: ${{ steps.release.outputs.pr }}
+        run: |
+          branch=$(jq -er '.headBranchName' <<< "$PR_JSON")
+          gh workflow run ci.yml --repo "$GITHUB_REPOSITORY" --ref "$branch"
+
+  target:
+    needs: release-please
+    if: >-
+      always() && github.ref == 'refs/heads/main' &&
+      (needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.resolve.outputs.tag }}
+      sha: ${{ steps.resolve.outputs.sha }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Resolve and validate release tag
+        id: resolve
+        env:
+          TAG: ${{ needs.release-please.outputs.tag_name || inputs.tag }}
+        run: |
+          [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo 'Expected a vMAJOR.MINOR.PATCH tag'; exit 1; }
+          sha=$(git rev-parse --verify "refs/tags/$TAG^{commit}")
+          git merge-base --is-ancestor "$sha" origin/main
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+
+  ci:
+    needs: target
+    if: always() && needs.target.result == 'success'
+    uses: ./.github/workflows/ci.yml
+    with:
+      ref: ${{ needs.target.outputs.sha }}
+    permissions:
+      contents: read
+
+  build:
+    needs: [target, ci]
+    if: always() && needs.ci.result == 'success' && needs.target.result == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          ref: ${{ needs.target.outputs.sha }}
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: uv sync --locked
+      - name: Version must match tag
+        env:
+          TAG: ${{ needs.target.outputs.tag }}
+        run: >-
+          uv run python -c 'import os, tomllib; from pathlib import Path;
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"];
+          assert os.environ["TAG"] == "v" + version, "Release tag does not match package version"'
+      - run: uv build
+      - run: uvx --from twine==6.2.0 twine check --strict dist/*.whl dist/*.tar.gz
+      - run: uv run poe distribution-check
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: python-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: release-archive
+          path: dist/*-release.zip
+          if-no-files-found: error
+
+  publish-pypi:
+    needs: [target, build]
+    if: always() && needs.build.result == 'success' && !inputs.testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ynab-api-cli/
+    permissions:
+      id-token: write
+      attestations: write
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: python-distributions
+          path: dist/
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-archive
+          path: release-assets/
+      - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: dist/*
+      - name: Publish through trusted publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+      - name: Attach distributions to GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.target.outputs.tag }}
+          SHA: ${{ needs.target.outputs.sha }}
+        run: |
+          if ! gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag --target "$SHA" --title "$TAG" --generate-notes
+          fi
+          gh release upload "$TAG" dist/* release-assets/* --repo "$GITHUB_REPOSITORY" --clobber
+
+  publish-testpypi:
+    needs: build
+    if: always() && needs.build.result == 'success' && inputs.testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/ynab-api-cli/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: python-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/

ynab_api_cli-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

ynab_api_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Provide a standalone YNAB REST API CLI with typed generated endpoints and request validation.
+- Include XDG connection configuration, diagnostics, discovery, mutation previews, and explicit execution guards.
+- Bundle the supplementary `ynab-api-cli` Codex skill and isolated live-test runner.
+- Verify reviewed operations, schema features, deterministic generation, and clean installation.

ynab_api_cli-0.1.0/PKG-INFO

@@ -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.

ynab_api_cli-0.1.0/README.md

@@ -0,0 +1,75 @@
+# 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.

ynab_api_cli-0.1.0/docs/live-testing.md

@@ -0,0 +1,27 @@
+# Isolated live testing
+
+Live testing is excluded from default pytest and scheduled CI. Every endpoint is tested offline; a live run reports its actual completed operations and capability gaps separately.
+
+1. Create a disposable YNAB plan manually. Its name must begin `YNAB API CLI TEST`; the API does not create plans.
+2. Create a separate protected auth.json for the test account. The runner never falls back to ordinary CLI credentials or a default plan.
+3. Run read-only checks first:
+
+   ```text
+   uv run poe live --plan-id EXPLICIT_UUID --auth-file /private/test/auth.json --state-directory /private/test/state
+   ```
+
+4. Enable writes only for that isolated plan:
+
+   ```text
+   uv run poe live --plan-id EXPLICIT_UUID --auth-file /private/test/auth.json --state-directory /private/test/state --enable-writes
+   ```
+
+The runner creates or reuses two accounts, a category group, a category, and a payee named with the `ynab-api-cli-test` prefix. These resources persist because the API has no corresponding delete operations. Do not mix unrelated data into them.
+
+It exercises transaction creation, bulk creation/update, splits, transfers, duplicate import IDs, scheduled transaction lifecycle, category/group/payee updates, and monthly budgeting. Created transaction records are deleted after verification where supported. Deleted records can remain as tombstones.
+
+Before each mutation, the runner writes a private intent journal. An uncertain operation leaves the intent unresolved, and subsequent runs stop. Inspect the recorded target and the actual API state before manually clearing `pending`; never simply rerun a failed write. Readback mismatches also require investigation.
+
+Payee-location reads require location fixtures. Direct Import needs a linked bank account; manual test accounts cannot verify actual bank imports. The report lists these gaps and never claims full live coverage when they remain.
+
+No live account connection is provisioned by installing this project. Supply credentials and a designated plan explicitly to run these tests.

ynab_api_cli-0.1.0/docs/maintenance.md

@@ -0,0 +1,19 @@
+# Contract maintenance
+
+The upstream contract is https://api.ynab.com/papi/open_api_spec.yaml. Runtime uses the bundled reviewed snapshot rather than silently adopting remote changes.
+
+1. Run `ynab-api-cli compat check` or `uv run poe compat-check`. Structural additions, removals, changed parameters, schemas, and server declarations fail compatibility. Documentation-only changes are reported separately.
+2. Inspect the candidate report, generated code, and typing results. Additions need reviewed catalog entries and independent wire fixtures; optional fields also require feature-matrix updates.
+3. Update the bundled specification and provenance deliberately. Regenerate through `uv run poe generate`; fix templates or documented transforms rather than generated output.
+4. Review the static operation catalog, schema-feature manifest, and independent fixtures. Never regenerate acceptance manifests automatically during CI.
+5. Run every quality gate, build distributions, and smoke-test a clean installation before releasing.
+
+The pinned openapi-python-client generator supplies parsed schema and endpoint structure. Custom templates emit Pydantic models and class-based typed methods. Deterministic transforms change relative imports to absolute imports, use StrEnum, resolve forward references, and create static endpoint dispatch. Naming overrides shorten duplicate nullable enum classes without changing wire values.
+
+Tests combine independently authored request expectations for every endpoint, runtime JSON Schema probes, a reviewed feature manifest, generated-model round trips, deliberate static typing failures, property tests, and failure-path tests. Synthetic schema responses supplement the independent wire fixtures; they are not evidence of live API behavior.
+
+The daily GitHub Actions workflow checks the public contract without account credentials. It becomes active only when this project is hosted in GitHub. Scheduled checks detect drift but never adopt it or run live writes.
+
+Semantic overlay: transaction creation must specify exactly one transaction representation, as documented in the createTransaction operation description. Milliunits, transfer linkage, split restrictions, import matching, and delta deletion semantics remain explicitly tested examples and documented API behavior; tests do not invent stricter server rules absent from the contract.
+
+The published OpenAPI 3.1 document retains legacy `nullable: true` annotations. Runtime validation maps them to explicit JSON Schema null branches, matching the generator's interpretation; the original snapshot stays unchanged. Nullable witnesses and typed additional-property models are tested.

ynab_api_cli-0.1.0/docs/privacy-review.md

@@ -0,0 +1,14 @@
+# Initial publication privacy review
+
+Reviewed on 2026-10-18 before uploading source to the public repository.
+
+- Git contained zero commits, no refs, and no reflog entries. There was no earlier commit history to sanitize. The initial commit uses a GitHub noreply address.
+- Reviewed authored source, generated source, templates, tests, fixtures, contract resources, skill resources, documentation, package metadata, and workflow configuration.
+- Removed an author email from package metadata and a machine-specific checkout path from documentation.
+- A detect-secrets 1.5.0 scan found only published contract SHA-256 fingerprints and ignored cache identifiers. Those were inspected as false positives. Additional credential-pattern, local-path, email, and credential-file searches found no sensitive publishable content.
+- Test tokens and records are synthetic. The specification and its examples come from the published YNAB contract. No personal YNAB records or credentials were used for tests or included in the source.
+- Credentials, environment files, caches, virtual environments, and build artifacts are excluded from Git. Old build artifacts were moved outside the repository before rebuilding under the new package name.
+- Extracted the rebuilt wheel, source distribution, and release archive. Credential-file and local-path searches found no sensitive content; secret detection on extracted source and wheel files found only the same reviewed contract hashes.
+- No credentials are copied from the former configuration directory. Connection setup remains a hidden local prompt.
+
+Secret scanners cannot prove the absence of every possible sensitive value. This review combines automated detection, inspection of scanner findings, and source/history checks; future contributions and releases require their own review.

ynab_api_cli-0.1.0/docs/publishing.md

@@ -0,0 +1,39 @@
+# Publishing ynab-api-cli
+
+The release workflow follows VerdiClip: Conventional Commits feed release-please, a reviewed version/changelog pull request produces a tag, and the tagged revision passes validation before upload. Wheels, source archives, and the supplementary skill are checked through a clean uv tool installation. The publishing job receives immutable build artifacts and uses short-lived GitHub OIDC credentials, PyPI attestations, and build provenance. No long-lived PyPI token is required.
+
+## Initial account setup
+
+1. Host this project in a GitHub repository with default branch `main` and enable Actions to create pull requests. Use the repository owner and name consistently below.
+2. Create the GitHub environment `pypi`. Restrict release workflows to `main`; add required reviewers if appropriate for the repository's ownership.
+3. In [PyPI account publishing](https://pypi.org/manage/account/publishing/), add a pending GitHub publisher with project name `ynab-api-cli`, the repository owner/name, workflow filename `release.yml`, and environment `pypi`.
+4. Optionally repeat for TestPyPI using environment `testpypi` and [TestPyPI account publishing](https://test.pypi.org/manage/account/publishing/).
+
+A pending publisher does not reserve or create a PyPI project. The first successful upload creates it, as described in the [PyPI documentation](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/). Account login, 2FA, and any required environment review must be completed by the appropriate account owner.
+
+## First release or retry
+
+Commit and push the fully validated source to `main`, create and push tag `v0.1.0` at that commit, then dispatch **Release** on `main` with `tag=v0.1.0` and `testpypi=false`. The workflow resolves the existing tag to a commit, verifies it belongs to main's history, tests that exact commit on Windows and Linux, checks its package version, builds distributions, and publishes them. A tag push alone does not publish.
+
+Use `testpypi=true` to publish to TestPyPI instead. TestPyPI has separate accounts and trusted-publisher configuration. Production publication deliberately does not skip existing versions; investigate a partial upload rather than silently treating it as a complete release.
+
+After publication, verify:
+
+```text
+uv tool install ynab-api-cli==0.1.0
+ynab-api-cli --help
+ynab-api-cli discover
+ynab-api-cli skill show
+```
+
+The package should appear at [PyPI](https://pypi.org/project/ynab-api-cli/) with wheel, source archive, and publishing attestations. The GitHub release also receives the standalone release archive.
+
+## Subsequent releases
+
+Use Conventional Commits on main. Release-please updates `pyproject.toml`, the project's package version in `uv.lock`, and `CHANGELOG.md`. Review and merge its pull request to create the release and run the same publication gates. A manual CI dispatch validates release-please pull requests even when GitHub suppresses automatic runs for its own bot token.
+
+`RELEASE_PLEASE_TOKEN` is optional; by default the workflow uses `GITHUB_TOKEN`. Repository settings must permit that token to create pull requests. No personal token is provisioned by this project.
+
+## Naming and connection configuration
+
+The package, executable, and skill are named `ynab-api-cli`; Python imports use `ynab_api_cli`. Configuration is read from `$XDG_CONFIG_HOME/ynab-api-cli/`, or `~/.config/ynab-api-cli/` when XDG_CONFIG_HOME is unset. It does not read the former generic directory. Run `ynab-api-cli configure` locally to create protected credentials at the new location; no credentials are copied automatically.

ynab_api_cli-0.1.0/docs/python-development-review.md

@@ -0,0 +1,76 @@
+# Python development review and disposable-plan testing
+
+Reviewed on 2026-10-18 against the installed `python-development` skill and its code, CLI, project, and testing references.
+
+## Verdict
+
+The supplementary YNAB skill has valid Codex metadata, uses progressive discovery, and matches its packaged copy. The Python CLI follows the required toolchain and layout, but it does **not fully comply** with the skill's manual design rules. Automated linting and typing do not establish full compliance.
+
+| Finding | Evidence | Required correction |
+| --- | --- | --- |
+| Construction performs I/O | `contract.py:36` reads contract resources; `live.py:40` reads the fixture journal; `__main__.py:31` constructs the contract | Move loading into explicit factories; inject loaded collaborators |
+| Services expose mutable implementation state | `live.py:45-58`, `contract.py`, and `__main__.py` | Use private attributes and deliberate public interfaces |
+| Generated models execute initialization during import | `generated/models/__init__.py:394` calls `ModelRegistry.rebuild()` | Resolve through generation templates and explicit initialization; never patch generated output manually |
+| Large classes combine responsibilities | `LiveRunner` spans more than 400 lines; `Application` owns multiple command handlers | Separate fixture lifecycle, journal persistence, and command handlers; use subcommand settings types |
+| Tests patch application internals | `test_cli.py:232`, `test_development.py:158`, and `test_live.py:265`; `SyntheticLive` overrides the runner's dispatch path | Inject collaborators and mock the HTTP/process boundary; retain end-to-end orchestration tests |
+| Live orchestration reads the clock directly | `live.py:56`, `live.py:255`, and `live.py:369` | Inject a clock for deterministic orchestration tests |
+
+The existing coverage threshold uses coverage.py's combined statement-and-branch metric. It does not independently enforce a minimum branch-only percentage. Generated code is excluded from runtime coverage, but included in strict typing and contract checks.
+
+Current validation results:
+
+- `uv run --offline --locked poe check`: passed; 147 tests, 96.34% combined coverage, and 319/346 branches covered (92.20%). Formatting, linting, and strict ty passed.
+- `uv run --offline --locked poe codegen-check`: passed; regeneration occurred in a temporary directory and matched checked-in generated source.
+- `uv run --offline --locked poe skill-check`: passed; canonical and packaged skill resources match.
+- Codex `skill-creator/scripts/quick_validate.py skills/ynab-api-cli`: passed.
+- Live-runner help and poe argument forwarding: checked without account access.
+- Upstream compatibility and clean-wheel installation were not rerun in this review; prior delivery results are documented separately in `verification.md`.
+
+## Test a real account with a disposable budget
+
+YNAB's current API calls budgets **plans**. Create a new, empty plan in the YNAB web application named `YNAB API CLI TEST - disposable`. Do not link bank accounts or copy real transactions into it.
+
+Generate your own personal access token under **Account Settings → Developer Settings → New Token**. See [YNAB's official authentication instructions](https://api.ynab.com/#personal-access-tokens). Enter the token only into the CLI's hidden local prompt. A separate configuration directory isolates local settings; it does not restrict the token to the dummy plan. The runner's explicit UUID and name check are application guards, not account permissions.
+
+Open a dedicated PowerShell terminal, then run:
+
+```powershell
+Set-Location 'path\to\ynab-api-cli'
+uv sync --locked
+$env:XDG_CONFIG_HOME = Join-Path $env:USERPROFILE '.config/ynab-api-cli-test'
+uv run ynab-api-cli configure
+uv run ynab-api-cli doctor
+uv run ynab-api-cli plans get-plans
+```
+
+Copy the UUID for the disposable plan from the output. Replace the placeholder below with that exact UUID:
+
+```powershell
+$testPlan = 'REPLACE-WITH-DISPOSABLE-PLAN-UUID'
+$testAuth = Join-Path $env:XDG_CONFIG_HOME 'ynab-api-cli/auth.json'
+$testState = Join-Path $env:USERPROFILE '.local/state/ynab-api-cli-test'
+uv run ynab-api-cli select-plan $testPlan
+uv run ynab-api-cli doctor
+uv run poe live --plan-id $testPlan --auth-file $testAuth --state-directory $testState
+```
+
+That first live run is read-only. It checks the plan identity and available read operations; missing fixture-dependent operations are expected. An offline doctor result cannot establish authentication or API access.
+
+When ready to create and update dummy records, run:
+
+```powershell
+uv run poe live --plan-id $testPlan --auth-file $testAuth --state-directory $testState --enable-writes
+```
+
+The live runner submits writes directly when `--enable-writes` is present; this is separate from the ordinary CLI's preview/`--execute` flow. It always requires the explicit plan and auth-file arguments and does not fall back to normal CLI defaults.
+
+## Interpret results and clean up
+
+- Review `completed_operations`, `missing_operations`, `gaps`, `retained_fixture_ids`, and `complete_live_coverage` in the JSON report. A successful process exit alone does not prove complete live coverage.
+- The runner exercises transaction creation, bulk changes, duplicate import IDs, splits, transfers, scheduled transactions, and category budgeting. It verifies many writes through subsequent reads. The current implementation does not independently read back every mutation, including category-group updates and split/transfer deletions.
+- Manual accounts cannot verify actual Direct Import. Payee-location tests also need suitable fixtures. Do not link a real bank solely to remove a coverage gap.
+- Accounts, category groups, categories, and payees remain for reuse; transaction deletions may leave API tombstones. Delete the entire disposable plan through YNAB after testing if you no longer need it.
+- On failure, inspect the journal at `<state-directory>/<plan-uuid>.json` and read the affected API records. Reconcile any `pending` mutation before changing the journal. Do not clear it and retry blindly.
+- Close the dedicated PowerShell terminal to discard its XDG override. Revoke the test token in Developer Settings when finished, and remove its isolated credential file when no longer needed.
+
+No real-account connection or live write was performed during this review. The procedure above is a path for user-run integration testing, not evidence that the live harness has already passed against YNAB.

ynab_api_cli-0.1.0/docs/verification.md

@@ -0,0 +1,34 @@
+# Delivery verification
+
+Verified on Windows with Python 3.12.13 on 2026-10-11.
+
+| Check | Result |
+| --- | --- |
+| Reviewed API surface | All 44 operations across 10 groups |
+| Reviewed schema witnesses | All 911 manifest entries exercised |
+| Generated client | Pinned openapi-python-client 0.29.0; reproducible generation |
+| Formatting, linting, and typing | Ruff and ty pass; every ty rule is an error |
+| Unit and contract tests | 147 tests pass; combined statement-and-branch coverage exceeds 96% |
+| codegen-check | Pass |
+| contract-check | Pass; independent wire cases, static typing cases, and schema tests |
+| compat-check | Pass against the published API 1.87.0; candidate generation, typing, and tests pass |
+| Skill | Valid frontmatter and matching canonical/package resources |
+| Distributions | Wheel and source archive contain required resources |
+| Clean installation | Temporary uv tool install passes help, discovery, inspection, offline doctor, and skill export |
+
+The default tests use synthetic credentials, temporary files, mock HTTP, and simulated live workflows. No real YNAB account was read or changed. Actual live tests require separately supplied protected credentials and an explicit disposable plan named with the `YNAB API CLI TEST` prefix.
+
+The GitHub Actions workflow is bundled but becomes active only after the project is hosted in GitHub. No repository publication or account provisioning was performed.
+
+## Rename and release-pipeline validation, 2026-10-18
+
+Renamed the package, executable, skill, and configuration directory to `ynab-api-cli`, with Python imports under `ynab_api_cli`. Regenerated all endpoint bindings and models through the maintained templates and transforms.
+
+- `poe check`: 147 tests passed; 96.34% combined statement-and-branch coverage.
+- `poe codegen-check`, `poe contract-check` (55 tests), and `poe compat-check` (63 candidate tests): passed. Upstream API remains 1.87.0 with no detected contract changes.
+- `poe skill-check` and Codex skill validation: passed.
+- Wheel, source archive, release archive, clean uv tool installation, and strict twine metadata validation: passed.
+- GitHub workflow actionlint and release-please schema validation: passed.
+- Source/history and extracted artifact privacy checks: completed; see [privacy review](privacy-review.md).
+
+These automated results do not resolve the manual design findings documented in [the Python development review](python-development-review.md). No live YNAB account was accessed.