bitwig-agent 0.1.1__tar.gz

bitwig_agent-0.1.1/.github/workflows/aur.yml

@@ -0,0 +1,95 @@
+name: Arch package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: arch-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  package:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    container:
+      image: archlinux:base-devel@sha256:3cbf69d2d5958d6a294f3722c5668e6187c4df8e00fa27f72352f0bf83e495e1
+    steps:
+      - name: Install distro build and check dependencies inside the disposable container
+        run: >-
+          pacman -Syu --noconfirm --needed
+          git python-build python-hatchling python-installer python-mcp python-pydantic
+          python-pytest python-numpy python-scipy python-soundfile namcap
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Require matching release, Python and Arch versions
+        id: version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          import tomllib
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          versions = [
+              line.partition("=")[2].strip()
+              for line in Path("packaging/aur/.SRCINFO").read_text().splitlines()
+              if line.strip().startswith("pkgver =")
+          ]
+          if versions != [version]:
+              raise SystemExit("Arch recipe version does not match Python metadata")
+          tag = os.environ.get("RELEASE_TAG", "")
+          ref = os.environ["GITHUB_REF"]
+          if not tag and ref.startswith("refs/tags/"):
+              tag = ref.removeprefix("refs/tags/")
+          if tag and tag != f"v{version}":
+              raise SystemExit("Selected release tag does not match package versions")
+          with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+              print(f"version={version}", file=output)
+          print(f"Arch release version: {version}")
+          PY
+      - name: Prepare an unprivileged package builder
+        run: |
+          useradd --create-home builder
+          install -d -o builder -g builder /home/builder/package
+          cp packaging/aur/PKGBUILD packaging/aur/.SRCINFO packaging/aur/LICENSE /home/builder/package/
+          chown -R builder:builder /home/builder/package
+      - name: Build the real release package and run its checks
+        working-directory: /home/builder/package
+        run: |
+          runuser -u builder -- makepkg --printsrcinfo | diff - .SRCINFO
+          runuser -u builder -- makepkg --cleanbuild --noconfirm
+          runuser -u builder -- makepkg --force --noconfirm
+          python - <<'PY'
+          from pathlib import Path
+          import subprocess
+
+          result = subprocess.run(
+              ["namcap", "PKGBUILD", *sorted(Path(".").glob("bitwig-agent-*.pkg.tar.zst"))],
+              text=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+          )
+          print(result.stdout, end="")
+          if result.returncode or any(" E: " in line for line in result.stdout.splitlines()):
+              raise SystemExit(1)
+          PY
+      - name: Install only inside the disposable container and exercise the consumer
+        env:
+          EXPECTED_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          # The base image's NoExtract omits docs; test the complete owned package.
+          printf '[options]\nArchitecture = auto\nSigLevel = Required DatabaseOptional\nLocalFileSigLevel = Optional\n' \
+            > /tmp/bitwig-pacman.conf
+          pacman --config /tmp/bitwig-pacman.conf -U --noconfirm /home/builder/package/bitwig-agent-*.pkg.tar.zst
+          runuser -u builder -- python -I scripts/smoke-package.py --expected-version "$EXPECTED_VERSION"
+          runuser -u builder -- bitwig-agent-install \
+            --extension /usr/share/bitwig-agent/BitwigAgent.bwextension
+          cmp /usr/share/bitwig-agent/BitwigAgent.bwextension \
+            '/home/builder/Bitwig Studio/Extensions/BitwigAgent.bwextension'
+          pacman -Qkk bitwig-agent

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

@@ -0,0 +1,112 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: Python ${{ matrix.python }} / MCP ${{ matrix.mcp }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.14"]
+        mcp: ["locked"]
+        include:
+          - python: "3.11"
+            mcp: "1.29.1"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: "0.13.5"
+          python-version: ${{ matrix.python }}
+      - name: Install locked development and audio-analysis dependencies
+        run: uv sync --locked --group native-music
+      - name: Install the minimum supported MCP SDK
+        if: matrix.mcp != 'locked'
+        run: uv pip install --python .venv/bin/python "mcp==${{ matrix.mcp }}"
+      - name: Run host-free Python checks
+        run: uv run --no-sync python scripts/check.py --layer offline
+
+  package:
+    name: Package / Python ${{ matrix.python }} / MCP ${{ matrix.mcp }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python: "3.14"
+            mcp: "current"
+          - python: "3.11"
+            mcp: "1.29.1"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: "0.13.5"
+          python-version: ${{ matrix.python }}
+      - name: Build source and wheel distributions
+        run: uv build --no-sources
+      - name: Exercise installed wheel and sdist consumers
+        env:
+          MCP_VERSION: ${{ matrix.mcp }}
+          PYTHON_VERSION: ${{ matrix.python }}
+        run: |
+          for distribution in dist/*.whl dist/*.tar.gz; do
+            consumer="$(mktemp -d "$RUNNER_TEMP/package-consumer.XXXXXX")"
+            uv venv --python "$PYTHON_VERSION" "$consumer/venv"
+            dependencies=("$PWD/$distribution")
+            if [[ "$MCP_VERSION" != current ]]; then
+              dependencies+=("mcp==$MCP_VERSION")
+            fi
+            uv pip install --no-cache --python "$consumer/venv/bin/python" "${dependencies[@]}"
+            "$consumer/venv/bin/python" -I scripts/smoke-package.py
+          done
+      - name: Validate the Agent Skills folder with the reference CLI
+        run: >-
+          uvx --from
+          'git+https://github.com/agentskills/agentskills.git@69ef37e9424c0a7ea9dd2293b559e43ec8176379#subdirectory=skills-ref'
+          skills-ref validate skills/bitwig-agent
+
+  secrets:
+    name: Reachable-history secret scan
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install checksum-pinned Gitleaks
+        run: |
+          curl --fail --silent --show-error --location \
+            https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz \
+            --output "$RUNNER_TEMP/gitleaks.tar.gz"
+          printf '%s  %s\n' \
+            '551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb' \
+            "$RUNNER_TEMP/gitleaks.tar.gz" | sha256sum --check
+          tar -xzf "$RUNNER_TEMP/gitleaks.tar.gz" -C "$RUNNER_TEMP" gitleaks
+      - name: Scan all reachable commits without suppression comments
+        run: |
+          "$RUNNER_TEMP/gitleaks" git . \
+            --log-opts='--all --full-history -m' \
+            --redact=100 --ignore-gitleaks-allow \
+            --gitleaks-ignore-path "$RUNNER_TEMP/no-gitleaks-ignore" \
+            --no-banner --no-color

bitwig_agent-0.1.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,204 @@
+name: Verify release / publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Publish the verified release to PyPI (requires configured Trusted Publisher and environment approval)
+        required: true
+        type: boolean
+        default: false
+
+permissions: {}
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify published GitHub release artifacts
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - name: Require a version tag
+        shell: bash
+        run: |
+          if [[ ! "$GITHUB_REF" =~ ^refs/tags/v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+            echo 'Dispatch this workflow on a vX.Y.Z tag, not a branch.' >&2
+            exit 1
+          fi
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: "0.13.5"
+          python-version: "3.11"
+          enable-cache: false
+      - name: Download and verify the reviewed release (never rebuild for promotion)
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          uv run --no-project --python 3.11 python - <<'PY'
+          from collections import Counter
+          from email.parser import BytesParser
+          import hashlib
+          import json
+          import os
+          from pathlib import Path
+          import re
+          import shutil
+          import subprocess
+          import tarfile
+          import tomllib
+          import zipfile
+
+          tag = os.environ["GITHUB_REF_NAME"]
+          version = tag.removeprefix("v")
+          project = tomllib.loads(Path("pyproject.toml").read_text())["project"]
+          if project["name"] != "bitwig-agent" or project["version"] != version:
+              raise SystemExit("Tag does not match pyproject.toml package/version")
+          wheel = f"bitwig_agent-{version}-py3-none-any.whl"
+          sdist = f"bitwig_agent-{version}.tar.gz"
+          extension = "BitwigAgent.bwextension"
+          required = {wheel, sdist, extension}
+          repo = os.environ["GITHUB_REPOSITORY"]
+          release = json.loads(subprocess.check_output([
+              "gh", "release", "view", tag, "--repo", repo,
+              "--json", "tagName,isDraft,assets",
+          ], text=True))
+          if release["tagName"] != tag or release["isDraft"]:
+              raise SystemExit("Expected a published GitHub release for this tag")
+          counts = Counter(asset["name"] for asset in release["assets"])
+          if any(counts[name] != 1 for name in required | {"SHA256SUMS"}):
+              raise SystemExit("Release must contain exactly one of each required asset")
+          downloads = Path(os.environ["RUNNER_TEMP"]) / "reviewed-release"
+          downloads.mkdir()
+          command = ["gh", "release", "download", tag, "--repo", repo, "--dir", str(downloads)]
+          for name in sorted(required | {"SHA256SUMS"}):
+              command.extend(["--pattern", name])
+          subprocess.run(command, check=True)
+          checksums = {}
+          for line in (downloads / "SHA256SUMS").read_text().splitlines():
+              match = re.fullmatch(r"([0-9a-fA-F]{64}) [ *]([^/\\\s]+)", line)
+              if match is None:
+                  raise SystemExit(f"Malformed SHA256SUMS entry: {line!r}")
+              digest, name = match.groups()
+              if name in checksums:
+                  raise SystemExit(f"Ambiguous checksum for {name}")
+              checksums[name] = digest.lower()
+          if set(checksums) != required:
+              raise SystemExit("SHA256SUMS must name exactly the wheel, sdist, and extension")
+          for name, expected in checksums.items():
+              with (downloads / name).open("rb") as stream:
+                  actual = hashlib.file_digest(stream, "sha256").hexdigest()
+              if actual != expected:
+                  raise SystemExit(f"SHA256 mismatch: {name}")
+              print(f"Verified SHA256 {actual}  {name}", flush=True)
+
+          def check_metadata(data, source):
+              metadata = BytesParser().parsebytes(data)
+              if metadata.get_all("Name") != ["bitwig-agent"] or metadata.get_all("Version") != [version]:
+                  raise SystemExit(f"Package name/version mismatch in {source}")
+
+          with zipfile.ZipFile(downloads / wheel) as archive:
+              entries = [entry for entry in archive.infolist()
+                         if entry.filename.endswith(".dist-info/METADATA")]
+              if len(entries) != 1:
+                  raise SystemExit("Expected exactly one wheel METADATA")
+              check_metadata(archive.read(entries[0]), wheel)
+          with tarfile.open(downloads / sdist, "r:gz") as archive:
+              entries = [entry for entry in archive.getmembers()
+                         if entry.name == f"bitwig_agent-{version}/PKG-INFO"]
+              if len(entries) != 1 or not entries[0].isfile():
+                  raise SystemExit("Expected exactly one regular sdist PKG-INFO")
+              with archive.extractfile(entries[0]) as stream:
+                  check_metadata(stream.read(), sdist)
+          # Only these original Python distributions can reach the publishing job.
+          destination = Path("dist")
+          destination.mkdir()
+          for name in (wheel, sdist):
+              shutil.copyfile(downloads / name, destination / name)
+          with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+              output.write(f"version={version}\n")
+          PY
+      - name: Smoke the actual release wheel and sdist outside the checkout
+        env:
+          RELEASE_VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          for distribution in dist/*.whl dist/*.tar.gz; do
+            consumer="$(mktemp -d "$RUNNER_TEMP/release-consumer.XXXXXX")"
+            uv venv --python 3.11 "$consumer/venv"
+            # No cache: the sdist must really build, not reuse the release wheel.
+            uv pip install --no-cache --python "$consumer/venv/bin/python" \
+              "$PWD/$distribution" 'mcp==1.29.1'
+            "$consumer/venv/bin/python" -I scripts/smoke-package.py \
+              --expected-version "$RELEASE_VERSION"
+          done
+      - name: Preserve verified Python distributions for promotion
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: verified-python-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 7
+      - name: Report verification (not publication)
+        env:
+          RELEASE_VERSION: ${{ steps.release.outputs.version }}
+          PUBLISH_REQUESTED: ${{ inputs.publish }}
+        run: |
+          {
+            echo "## GitHub release v$RELEASE_VERSION verified"
+            echo 'Verified the wheel, sdist, and extension SHA256 checksums and Python package/tag versions.'
+            echo 'Installed wheel and sdist consumers passed offline CLI and real MCP discovery with Python 3.11 / MCP 1.29.1.'
+            echo 'No native Bitwig test or PyPI upload occurred in this job.'
+            if [[ "$PUBLISH_REQUESTED" == true ]]; then
+              echo 'Publication was requested; only the separate environment-gated publish job can report an upload.'
+            else
+              echo 'Verification-only run: publication was not requested.'
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  publish:
+    name: Publish verified artifacts to PyPI
+    needs: verify
+    if: inputs.publish
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/bitwig-agent/
+    permissions:
+      id-token: write
+    steps:
+      # Deliberately no checkout, builds, installs of this package, or source execution.
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: "0.13.5"
+          enable-cache: false
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: verified-python-distributions
+          path: dist/
+      - name: Generate PEP 740 publish attestations
+        uses: astral-sh/attest-action@39b6ce43875c196a579e31635b11aa2a2036384a # v0.0.7
+        with:
+          paths: dist/*
+      - name: Publish with mandatory OIDC Trusted Publishing
+        run: uv publish --trusted-publishing always dist/*.whl dist/*.tar.gz
+      - name: Report successful publication
+        env:
+          RELEASE_VERSION: ${{ needs.verify.outputs.version }}
+        run: |
+          {
+            echo "## Published bitwig-agent $RELEASE_VERSION to PyPI"
+            echo 'Uploaded the verified GitHub release wheel and sdist with PEP 740 publish attestations via OIDC Trusted Publishing.'
+          } >> "$GITHUB_STEP_SUMMARY"

bitwig_agent-0.1.1/.gitignore

@@ -0,0 +1,40 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+build/
+.deps/
+*.egg-info/
+.DS_Store
+dist/
+.package-venv/
+
+# Local credentials and runtime configuration.
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+
+# Private development evidence and continuation records are not publication inputs.
+/runs/
+/research/
+/review/
+/docs/history/
+/AGENTS.md
+/HANDOFF.md
+/scripts/grid-compatibility.py
+/scripts/inventory-api.py
+/tests/grid-cases.json
+
+# Native projects, renders, host binaries and locally built extensions.
+*.bwproject
+*.bwpreset
+*.wav
+*.bwextension
+*.jar
+*.class
+*.so

bitwig_agent-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing
+
+Keep changes focused on helping agents complete real Bitwig tasks. Domain operations belong in their existing modules; transport, validation and native bindings remain separate. Do not add automatic retries or GUI fallback for uncertain writes.
+
+## Source setup
+
+End users should use the [released wheel and extension](README.md#quickstart). Development requires a checkout, Python 3.11+, [uv](https://docs.astral.sh/uv/getting-started/installation/), **JDK 25+**, and your own licensed Bitwig installation with its API 25 host JAR. The Bitwig 6.1.3 loader superclass uses class-file version 69, so JDK 25 is needed to compile/run Java checks; generated extension classes still target Java 11.
+
+From the repository root:
+
+```sh
+uv sync --locked
+export BITWIG_API_JAR=/path/to/installed/bitwig.jar
+export JAVAC=/path/to/jdk25/bin/javac
+export JAVA=/path/to/jdk25/bin/java
+uv run --locked python scripts/build.py
+uv run --locked bitwig-agent-install --extension build/BitwigAgent.bwextension
+```
+
+The API JAR defaults to `/opt/bitwig-studio/bin/bitwig.jar`; override it for your installation. The build downloads and verifies pinned Gson on first use. Neither the proprietary host JAR nor JDK is bundled. Installation does not enable the controller: follow [the enable/connect steps](README.md#2-enable-in-bitwig). For a checkout-based MCP configuration, run `uv run --locked bitwig-agent-install --mcp-config`; keep the checkout environment available to the client.
+
+## Development checks
+
+Use Python 3.11+ and uv. Install optional audio-analysis dependencies so the offline suite exercises its PCM checks rather than skipping them:
+
+```sh
+uv sync --locked --group native-music
+uv run --locked python scripts/check.py --layer offline
+```
+
+For the Java build, simulated-host checks and real MCP/Java fixture, install JDK 25+ and supply your own compatible Bitwig API JAR:
+
+```sh
+export BITWIG_API_JAR=/path/to/installed/bitwig.jar
+export JAVAC=/path/to/jdk25/bin/javac
+export JAVA=/path/to/jdk25/bin/java
+uv run --locked python scripts/build.py
+uv run --locked python scripts/check.py
+```
+
+The default checks do not launch Bitwig. See [VERIFICATION.md](VERIFICATION.md) for layer boundaries. CI covers host-free Python checks, minimum supported MCP, Python package consumption, skill format and a reachable-history secret scan; local Arch packaging is a separate downstream check. None claims to build against or test a live proprietary host. Consult actual workflow output rather than treating configured jobs as passing evidence.
+
+## Changes and bug reports
+
+- Describe the observable behavior, affected methods and checks actually run. Add a deterministic regression test for a consumer-visible bug when practical.
+- Keep MCP and CLI schemas consistent with Java validation and [PROTOCOL.md](PROTOCOL.md).
+- Distinguish dispatch, model readback, GUI completion, audio output and persistence. Do not report an unknown write as failed-and-safe-to-repeat.
+- Native work requires a disposable project and one designated writer. Never use a user's active project as an automatic test fixture.
+- Review staged files before committing. Do not submit credentials, private conversations, raw machine/process snapshots, original tool-call identifiers, personal paths, Bitwig host binaries or proprietary factory assets. Use minimal synthetic reproductions and redacted diagnostics.
+- Preserve third-party notices. Project contributions are distributed under the [MIT License](LICENSE); third-party material retains its own applicable license.
+
+For security-sensitive issues, use the private route in [SECURITY.md](SECURITY.md), not a public issue containing exploit details or private data.
+
+## Release procedure
+
+See [packaging and release promotion](docs/packaging.md) for the complete artifact, Arch and PyPI contract. Releases are built locally against a maintainer's licensed Bitwig JAR; public CI does not have that dependency. The commands below use **0.1.1**; they are instructions, not evidence that any check ran.
+
+1. Start from reviewed source, align Python/MCP/extension versions and installation links, and run the applicable [layered checks](VERIFICATION.md). Keep actual results; list native checks not performed.
+2. Build the Python wheel **and sdist**, plus the matching extension:
+
+   ```sh
+   uv sync --locked
+   uv build
+   uv run --locked python scripts/build.py
+   sha256sum dist/bitwig_agent-0.1.1-py3-none-any.whl dist/bitwig_agent-0.1.1.tar.gz build/BitwigAgent.bwextension
+   ```
+
+3. Create `SHA256SUMS` from those actual hashes with exactly three unique **bare asset filenames**, removing local `dist/` and `build/` prefixes. Inspect artifact contents and third-party notices. Never upload the proprietary host JAR, factory assets or private machine/evidence data.
+4. Finalize [the Arch recipe](https://github.com/BANANASJIM/bitwig-agent/tree/main/packaging/aur) from those exact candidate artifacts and regenerate `.SRCINFO` **before tagging**. Validate it in an isolated Arch environment; its source cache may be prefilled with the exact candidate sdist and version-aliased extension. `packaging/` is excluded from the sdist, so updating its hashes does not require rebuilding that sdist.
+5. Commit the reviewed source, recipe and metadata, then tag it as `v0.1.1`. Publish the same wheel, sdist, extension and manifest to its GitHub release. Include the actual tested platform/host scope and unresolved limitations. Do not mutate previous release artifacts.
+6. Exercise the real GitHub wheel/download path in an isolated environment outside the checkout, using an isolated extension destination, offline CLI and the generated configuration's MCP handshake. Confirm the release-triggered Arch workflow builds the matching version from published downloads. A live status/editing check is separate and requires permission, one writer and a disposable project; recipe verification is not an AUR upload.
+7. Run `publish-pypi.yml` on the version tag with `publish=false` for promotion validation. Only an explicitly authorized publication with the configured `pypi` environment and Trusted Publisher may use `publish=true`. Promote the same reviewed artifacts, not a separate rebuild. See [external account prerequisites](docs/packaging.md#external-accountenvironment-prerequisites).
+
+Neither a pending PyPI publisher nor an AUR recipe establishes public package availability. Keep GitHub wheel installation as the documented path until the relevant registry/version actually exists.
+
+## Agent skill maintenance
+
+The portable skill is [`skills/bitwig-agent`](https://github.com/BANANASJIM/bitwig-agent/tree/main/skills/bitwig-agent). Keep its main `SKILL.md` short; place focused guidance one directory level down in `references/`, with every reference directly reachable from `SKILL.md`. Bundle its MIT `LICENSE` so the folder can be copied alone. Links outside that folder must use public repository URLs, not checkout-relative paths. Do not embed host identities, private paths, credentials, global client configuration changes or a tool permission grant.
+
+Use the [Agent Skills specification](https://agentskills.io/specification) and the demonstration `skills-ref` validator pinned to the reviewed source commit:
+
+```sh
+uvx --from "git+https://github.com/agentskills/agentskills.git@69ef37e9424c0a7ea9dd2293b559e43ec8176379#subdirectory=skills-ref" skills-ref validate skills/bitwig-agent
+```
+
+This command fetches a validation tool; it is not a production DAW dependency. Format/frontmatter validation does **not** establish correct tool use, native behavior, compatibility, permissions or musical acceptance. Separately review the copied folder's local references and safety instructions: fresh schema/target discovery, explicit permission, unknown-stop discipline and no implicit GUI fallback.
+
+## Repository map and architecture
+
+See [architecture and ownership](docs/architecture.md) for the detailed public-code walkthrough. Python MCP stdio and CLI entrypoints share a strict schema/catalog and loopback client. The Java extension dispatches bounded newline-delimited JSON requests through host scheduling into separate domains. Bitwig owns the project/audio engine; the bridge is not a complete project mirror and never automatically retries requests.
+
+| Path | Responsibility |
+|---|---|
+| `src/bitwig_agent/` | Schemas/catalog, transport, MCP, CLI and release installer |
+| `extension/src/main/java/dev/bitwigagent/` | Host services, domains and bounded native adapters |
+| `extension/src/test/`, `tests/` | Simulated-host Java checks and host-free Python regressions |
+| `scripts/` | Source builds/checks and offline evidence helpers |
+| `examples/` | Client configuration and explicit opt-in music recipes |
+| `docs/` | Public architecture, installation navigation and packaging guides |
+| `packaging/aur/` | Local Arch recipe and synchronized `.SRCINFO` |
+| `skills/bitwig-agent/` | Copyable Agent Skills instructions, focused references and MIT license |
+
+The default-package `extension/src/main/java/BitwigAgent613GridInsertion.java` is intentional: its native superclass is also in the unnamed package and it is loaded by that exact class name. Historical evidence is not active test infrastructure; use [VERIFICATION.md](VERIFICATION.md) for current checks.