archastro-sdk 0.1.1__tar.gz

archastro_sdk-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-test:
+    name: Lint + Test (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup Node (for @archastro/channel-harness + prism)
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci --ignore-scripts
+
+      - name: Audit JS tooling dependencies
+        run: npm audit --audit-level=moderate
+
+      - name: Setup Python ${{ matrix.python }}
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          version: "0.11.3"
+          checksum: c0f3236f146e55472663cfbcc9be3042a9f1092275bbe3fe2a56a6cbfd3da5ce
+          enable-cache: true
+
+      - name: Install project + dev deps
+        run: uv sync --locked --all-extras
+
+      - name: Ruff lint
+        run: uv run ruff check
+
+      - name: Ruff format check
+        run: uv run ruff format --check
+
+      - name: Unit tests
+        run: uv run pytest tests/test_http_client.py src/archastro/phx_channel/tests/test_unit.py
+
+      - name: Harness-client integration tests
+        run: uv run pytest tests/harness
+
+      - name: Contract tests (REST + channels over real harness subprocess)
+        run: uv run pytest tests/contract
+        env:
+          ARCHASTRO_RUN_CHANNEL_CONTRACT_TESTS: "1"
+
+      - name: Build and import wheel
+        run: |
+          rm -rf dist
+          uv build --no-build-isolation
+          uv export --locked --no-dev --no-emit-project --format requirements.txt --output-file dist/runtime-requirements.txt >/dev/null
+          uv venv --clear .wheel-smoke
+          uv pip install --python .wheel-smoke --require-hashes -r dist/runtime-requirements.txt
+          uv pip install --python .wheel-smoke --no-deps dist/*.whl
+          .wheel-smoke/bin/python -c "import archastro.platform; import archastro.phx_channel"

archastro_sdk-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,97 @@
+name: Publish
+
+# Triggered by the tags that release.yml pushes (v*), and reachable via
+# workflow_dispatch so release.yml can re-trigger after pushing the tag —
+# tags pushed by GITHUB_TOKEN don't themselves trigger workflows.
+#
+# Authenticates to PyPI via OIDC (Trusted Publishing) — no PYPI_API_TOKEN.
+#
+# Prereqs (one-time):
+#   1. First publish done manually from a laptop (uv publish or twine upload)
+#   2. Trusted publisher configured at pypi.org/manage/project/archastro-sdk/
+#      pointing at this workflow filename (publish.yml) and the `pypi`
+#      environment used below.
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: write      # create GitHub Release
+  id-token: write      # OIDC token for PyPI Trusted Publishing
+
+jobs:
+  publish:
+    name: PyPI publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/archastro-sdk
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup Python
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          version: "0.11.3"
+          checksum: c0f3236f146e55472663cfbcc9be3042a9f1092275bbe3fe2a56a6cbfd3da5ce
+          enable-cache: true
+
+      - name: Install project + dev deps
+        run: uv sync --locked --all-extras
+
+      - name: Resolve version from tag
+        id: pkg
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          case "$TAG" in
+            v*)
+              echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              echo "Unrecognized tag: $TAG (expected v*)" >&2
+              exit 1
+              ;;
+          esac
+
+      - name: Verify pyproject.toml version matches tag
+        env:
+          EXPECTED: ${{ steps.pkg.outputs.version }}
+        run: |
+          set -euo pipefail
+          actual=$(uv run python -c "import tomllib, sys; print(tomllib.loads(open('pyproject.toml','rb').read().decode())['project']['version'])")
+          if [ "$actual" != "$EXPECTED" ]; then
+            echo "Version mismatch: tag says $EXPECTED, pyproject.toml says $actual" >&2
+            exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: |
+          rm -rf dist
+          uv build --no-build-isolation
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # release/v1
+        # Defaults: reads dist/, uses OIDC when id-token: write is set + a
+        # trusted publisher is configured for this repo + workflow + env.
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+          VERSION: ${{ steps.pkg.outputs.version }}
+        run: |
+          set -euo pipefail
+          gh release create "$TAG" \
+            --title "archastro-sdk v$VERSION" \
+            --notes "Published to PyPI: https://pypi.org/project/archastro-sdk/$VERSION/" \
+            --generate-notes

archastro_sdk-0.1.1/.github/workflows/regenerate-sdk.yml

@@ -0,0 +1,138 @@
+name: Regenerate SDK
+
+# Manually trigger from the Actions tab to pull the latest spec from
+# archastro-openapi and re-run @archastro/sdk-generator. If anything
+# changes, the workflow force-pushes to a stable branch and opens (or
+# updates) a PR to main for review.
+#
+# No build/test step here — the PR's own CI runs them.
+
+on:
+  workflow_dispatch:
+    inputs:
+      openapi_ref:
+        description: archastro-openapi git ref to pull spec from
+        required: false
+        default: main
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  AUTO_BRANCH: auto/regenerate-sdk
+
+jobs:
+  regenerate:
+    name: Regenerate + open PR
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install latest SDK tooling
+        run: |
+          set -euo pipefail
+          npm install --ignore-scripts --save-dev \
+            @archastro/sdk-generator@latest \
+            @archastro/channel-harness@latest
+          npm pkg set \
+            devDependencies.@archastro/sdk-generator=latest \
+            devDependencies.@archastro/channel-harness=latest
+          npm install --package-lock-only --ignore-scripts
+
+      - name: Audit JS tooling dependencies
+        run: npm audit --audit-level=moderate
+
+      - name: Setup Python
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          version: "0.11.3"
+          checksum: c0f3236f146e55472663cfbcc9be3042a9f1092275bbe3fe2a56a6cbfd3da5ce
+          enable-cache: true
+
+      - name: Install project + dev deps
+        # Required because the regen script invokes `uv run ruff ...` to
+        # normalize formatting on the generated tree.
+        run: uv sync --locked --all-extras
+
+      - name: Regenerate SDK
+        env:
+          ARCHASTRO_OPENAPI_REF: ${{ inputs.openapi_ref }}
+        run: ./scripts/regenerate_sdk.sh
+
+      - name: Detect changes
+        id: diff
+        run: |
+          if [ -z "$(git status --porcelain package.json package-lock.json src tests specs)" ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "No changes from regeneration; nothing to do."
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            git status --short package.json package-lock.json src tests specs
+          fi
+
+      - name: Resolve generator version
+        if: steps.diff.outputs.changed == 'true'
+        id: gen
+        run: |
+          set -euo pipefail
+          resolved=$(node -p "require('./node_modules/@archastro/sdk-generator/package.json').version")
+          echo "version=$resolved" >> "$GITHUB_OUTPUT"
+
+      - name: Commit + force-push to ${{ env.AUTO_BRANCH }}
+        if: steps.diff.outputs.changed == 'true'
+        env:
+          REF: ${{ inputs.openapi_ref }}
+          GEN_VERSION: ${{ steps.gen.outputs.version }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -B "$AUTO_BRANCH"
+          git add package.json package-lock.json src tests specs
+          git commit -m "chore(sdk): regenerate from archastro-openapi@$REF (generator $GEN_VERSION)"
+          git push --force-with-lease origin "$AUTO_BRANCH"
+
+      - name: Open or update PR
+        if: steps.diff.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REF: ${{ inputs.openapi_ref }}
+          GEN_VERSION: ${{ steps.gen.outputs.version }}
+        run: |
+          set -euo pipefail
+          file_count=$(git diff --name-only HEAD~1 HEAD -- package.json package-lock.json src tests specs | wc -l | tr -d ' ')
+          body=$(cat <<EOF
+          Automated SDK regeneration.
+
+          - **archastro-openapi ref**: \`$REF\`
+          - **generator version**: \`$GEN_VERSION\` resolved from npm latest and locked in package-lock.json
+          - **changed files**: $file_count
+
+          Review the diff carefully — generator output changes can be subtle. The PR's CI will run lint + tests.
+          EOF
+          )
+
+          existing=$(gh pr list --head "$AUTO_BRANCH" --state open --json number --jq '.[0].number // empty')
+          if [ -n "$existing" ]; then
+            echo "Updating PR #$existing"
+            gh pr edit "$existing" --body "$body"
+          else
+            echo "Opening new PR"
+            gh pr create \
+              --base main \
+              --head "$AUTO_BRANCH" \
+              --title "chore(sdk): regenerate from openapi@$REF" \
+              --body "$body"
+          fi

archastro_sdk-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,157 @@
+name: Release
+
+# Manually trigger from the Actions tab to:
+#   1. Bump pyproject.toml + uv.lock versions on a release branch
+#   2. Push a tag (vX.Y.Z) which triggers publish.yml
+#   3. Open a PR back to main and merge it so main tracks the bump
+#
+# Publishing uses PyPI Trusted Publishing (OIDC) — no PYPI_API_TOKEN.
+# A package's first publish must be done manually; after that, configure a
+# trusted publisher on pypi.org pointing at publish.yml.
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version bump
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: write
+  pull-requests: write
+  actions: write           # to dispatch publish.yml via `gh workflow run`
+
+jobs:
+  release:
+    name: Bump + branch + tag
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci --ignore-scripts
+
+      - name: Audit JS tooling dependencies
+        run: npm audit --audit-level=moderate
+
+      - name: Setup Python
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          version: "0.11.3"
+          checksum: c0f3236f146e55472663cfbcc9be3042a9f1092275bbe3fe2a56a6cbfd3da5ce
+          enable-cache: true
+
+      - name: Install project + dev deps
+        run: uv sync --locked --all-extras
+
+      - name: Test (sanity gate before bumping)
+        # Core CI gates on Python 3.12 only — keeps the release gate honest
+        # without spending time on the full ci.yml matrix.
+        run: |
+          uv run ruff check
+          uv run ruff format --check
+          uv run pytest tests/test_http_client.py src/archastro/phx_channel/tests/test_unit.py
+          uv run pytest tests/harness
+          uv run pytest tests/contract
+          rm -rf dist
+          uv build --no-build-isolation
+          uv export --locked --no-dev --no-emit-project --format requirements.txt --output-file dist/runtime-requirements.txt >/dev/null
+          uv venv --clear .wheel-smoke
+          uv pip install --python .wheel-smoke --require-hashes -r dist/runtime-requirements.txt
+          uv pip install --python .wheel-smoke --no-deps dist/*.whl
+          .wheel-smoke/bin/python -c "import archastro.platform; import archastro.phx_channel"
+        env:
+          ARCHASTRO_RUN_CHANNEL_CONTRACT_TESTS: "1"
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        id: bump
+        env:
+          BUMP: ${{ inputs.bump }}
+        run: |
+          set -euo pipefail
+          # `uv version --bump` updates pyproject.toml + uv.lock atomically.
+          uv version --bump "$BUMP"
+          version=$(uv run python -c "import tomllib; print(tomllib.loads(open('pyproject.toml','rb').read().decode())['project']['version'])")
+          tag="v$version"
+          branch="release/$tag"
+          {
+            echo "version=$version"
+            echo "tag=$tag"
+            echo "branch=$branch"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Commit + push release branch
+        env:
+          BRANCH: ${{ steps.bump.outputs.branch }}
+          VERSION: ${{ steps.bump.outputs.version }}
+        run: |
+          set -euo pipefail
+          git checkout -b "$BRANCH"
+          git add pyproject.toml uv.lock
+          git commit -m "release: archastro-sdk v$VERSION"
+          git push origin "$BRANCH"
+
+      - name: Create + push tag
+        env:
+          TAG: ${{ steps.bump.outputs.tag }}
+        run: |
+          set -euo pipefail
+          git tag -a "$TAG" -m "$TAG"
+          git push origin "$TAG"
+
+      - name: Dispatch publish.yml for the tag
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.bump.outputs.tag }}
+        run: |
+          set -euo pipefail
+          echo "Dispatching publish.yml --ref $TAG"
+          gh workflow run publish.yml --ref "$TAG"
+
+      - name: Open PR + merge
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: ${{ steps.bump.outputs.branch }}
+          VERSION: ${{ steps.bump.outputs.version }}
+          TAG: ${{ steps.bump.outputs.tag }}
+        run: |
+          set -euo pipefail
+          body=$(cat <<EOF
+          Automated release — version bump opened by \`release.yml\`.
+
+          **Tag pushed** (publish.yml is publishing right now):
+          - \`$TAG\`
+
+          This PR merges immediately so \`main\` stays in sync with what
+          was published. Tests already ran above; the bump is the only
+          change in this PR.
+          EOF
+          )
+          pr_url=$(gh pr create \
+            --base main \
+            --head "$BRANCH" \
+            --title "release: archastro-sdk v$VERSION" \
+            --body "$body")
+          gh pr merge "$pr_url" --squash --delete-branch
+          echo "Merged $pr_url"

archastro_sdk-0.1.1/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.venv/
+
+# Node tooling (for @archastro/channel-harness + prism)
+node_modules/
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/

archastro_sdk-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArchAstro Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archastro_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: archastro-sdk
+Version: 0.1.1
+Summary: Python SDK for the ArchAstro Platform API
+Project-URL: Homepage, https://github.com/ArchAstro/archastro-python
+Project-URL: Repository, https://github.com/ArchAstro/archastro-python
+Project-URL: Issues, https://github.com/ArchAstro/archastro-python/issues
+Author-email: ArchAstro <support@archastro.ai>
+License: MIT License
+        
+        Copyright (c) 2026 ArchAstro Inc.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,archastro,phoenix-channels,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: hatchling>=1.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# archastro-python
+
+Python SDK for the ArchAstro Platform API.
+
+```bash
+uv add archastro-sdk      # or: pip install archastro-sdk
+```
+
+```python
+from archastro import ArchAstro
+
+client = ArchAstro(api_key="pk_...")
+teams = client.v1.teams.list()
+```
+
+## Packages
+
+All public code lives under the single top-level `archastro` package:
+
+- **`archastro.platform`** — typed REST + channel SDK generated from
+  the canonical OpenAPI spec at
+  [`ArchAstro/archastro-openapi`](https://github.com/ArchAstro/archastro-openapi).
+  Pydantic models, async channel classes, auth helpers.
+- **`archastro.phx_channel`** — the hand-written Phoenix Channels
+  client the generated channel classes run on top of. WebSocket
+  transport, join / reply / push / leave, heartbeat, reconnect, and a
+  `HarnessServiceClient` for driving the
+  [`@archastro/channel-harness`](https://www.npmjs.com/package/@archastro/channel-harness)
+  service from Python tests.
+
+## Development
+
+This repo contains:
+
+- Python SDK (`src/archastro/`) installed via `uv`
+- JS tooling (`package.json`) — the channel-harness subprocess that
+  powers the channel contract tests, plus the Prism mock server that
+  backs the REST contract tests. Installed via `npm ci`.
+
+### Setup
+
+```bash
+npm ci --ignore-scripts  # channel-harness + prism (for contract tests)
+uv sync --locked --all-extras
+```
+
+### Running tests
+
+```bash
+# Unit tests only (no external services needed)
+uv run pytest tests/test_http_client.py src/archastro/phx_channel/tests/test_unit.py
+
+# REST contract tests (spawns Prism mock server)
+uv run pytest tests/contract
+
+# REST + channel contract tests (also spawns channel-harness subprocess)
+ARCHASTRO_RUN_CHANNEL_CONTRACT_TESTS=1 uv run pytest tests/contract
+```
+
+### Regenerating the SDK
+
+The typed SDK — `src/archastro/platform/` and `tests/contract/` — is
+regenerated from the canonical OpenAPI spec by
+[`@archastro/sdk-generator`](https://www.npmjs.com/package/@archastro/sdk-generator).
+Don't hand-edit files with the `auto-generated by @archastro/sdk-generator`
+header; they'll be overwritten.
+
+```bash
+./scripts/regenerate_sdk.sh
+```
+
+The script fetches the spec from `ArchAstro/archastro-openapi@main` and
+runs the generator locked in `package-lock.json`. Knobs:
+
+- `ARCHASTRO_OPENAPI_REF=some-branch ./scripts/regenerate_sdk.sh` — pull
+  the spec from a non-default ref (useful when a spec change is on a
+  branch awaiting merge).
+
+After regenerating, review the diff, run the full test suite, and commit.
+
+## Release
+
+```bash
+# bump version in pyproject.toml, then:
+uv sync --locked --all-extras
+uv build --no-build-isolation
+uv publish
+```