macos-computer-use-kit 0.2.0__tar.gz

macos_computer_use_kit-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  python:
+    # Real macOS runner: the CLI is macOS-only, and doctor must not crash in CI
+    # where the TCC permissions are absent.
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: python -m pip install --upgrade pip && pip install -e ".[dev]"
+      - name: Unit tests
+        run: pytest -q
+      - name: CLI smoke (doctor reports missing permissions instead of crashing)
+        run: |
+          macos-cu --version
+          macos-cu doctor || true
+      - name: Byte-compile every module and shim
+        run: python -m compileall -q src tools
+
+  packages:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        package: [packages/pi, packages/dsh]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Install (runs the dsh bundle `prepare` build)
+        working-directory: ${{ matrix.package }}
+        run: npm ci
+      - name: Typecheck
+        working-directory: ${{ matrix.package }}
+        run: npm run typecheck

macos_computer_use_kit-0.2.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/
+venv/
+
+# Node
+node_modules/
+
+# Built dsh bundle output (rebuilt by `prepare` on install/publish)
+packages/*/lib/
+
+# Runtime artifacts
+.runtime/
+*.png
+
+# macOS
+.DS_Store

macos_computer_use_kit-0.2.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project. The CLI, the pi package, and the dsh bundle
+share a version number.
+
+## 0.2.0
+
+First release meant for use outside the machine it was built on.
+
+**Packaging**
+- Ship an installable Python package (`macos-computer-use-kit`) with a `macos-cu`
+  console script. Previously the toolkit was a folder of scripts plus a
+  hand-made virtualenv at a fixed absolute path.
+- `tools/*.py` remain as compatibility shims over the same modules.
+- Add `packages/pi` (`pi-package`: skill + 9 tools) and `packages/dsh` (Cordis
+  bundle: `cordis.patch.yml` + 5 tools). Both bridge to the CLI with argv arrays
+  (`shell: false`) and resolve it from known install locations, so a
+  GUI-launched agent works without an interactive shell's `PATH`.
+- `install.sh` now provisions a venv, a launcher, the agent skill, and the
+  optional Jev key, and picks whichever package index answers faster.
+
+**Portability fixes**
+- Remove the hardcoded display scale (`0.9333 = 1372/1470`); `--shot-scale` is
+  explicit opt-in and there is no fake default.
+- Stop hardcoding the overlay path, the snapshot cache directory, and the
+  `/tmp/shot.png` capture path.
+- Add `unsupported_platform` / `missing_dependency` JSON errors instead of a
+  pyobjc traceback or a shell error.
+- Deterministic app resolution: exact bundle id, exact localized name,
+  case-insensitive exact, then substring; frontmost apps win ties. The old
+  behaviour took the first substring match, which could target the wrong app.
+- Prefer `NSPasteboardTypeString`, falling back to the legacy
+  `NSStringPboardType`.
+
+**Behaviour fixes**
+- `ax find` now honours `--max` (it used to return every match, flooding
+  context).
+- `input windows --pid` actually filters by pid.
+- `doctor` reports platform, permissions, display geometry, dependencies, and
+  Jev setup as JSON, with actionable hints.
+- The Jev guard policy is a pure `decide()` function; the model version is
+  pinnable with `TYPESAFE_MODEL`.
+
+**Documentation**
+- English-first README and skill, with a concise Chinese section; machine- and
+  app-specific walkthroughs replaced by generic examples.
+- `PUBLISHING.md` with the npm/PyPI release steps and catalog-listing criteria.
+- Correct the dependency list (`pyobjc-framework-AppKit` does not exist; AppKit
+  ships in `pyobjc-framework-Cocoa`).
+
+**Tests and CI**
+- Unit tests for the guard policy and the window target signature.
+- GitHub Actions: tests and a compile check on macOS, typecheck for both npm
+  packages.
+
+## 0.1.0
+
+Initial extraction of the toolkit from three implementations (Codex CUA, ZCode
+Computer Use, Grok Bot), with `ax_tool.py`, `assist.py`, `smart_paste.py`,
+`shot.py`, `overlay.py`, `guard.py`, `jev_select.py`, and an agent skill.

macos_computer_use_kit-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Bug reports, platform findings, and pull requests are welcome. This toolkit
+drives real desktops, so evidence beats opinion: paste the JSON a command
+returned, the macOS version, and the app you were driving.
+
+## Layout
+
+```
+src/macos_computer_use/   the CLI (single source of truth)
+tools/*.py                compatibility shims over the same modules
+skill/                    agent skill + Jev reference
+packages/pi/              pi package (skill + tools; sources, no build)
+packages/dsh/             DeepSeek Harness bundle (TypeScript -> lib/)
+tests/                    unit tests for pure logic
+```
+
+## Develop
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest -q
+macos-cu doctor
+
+(cd packages/pi  && npm ci && npm run typecheck)
+(cd packages/dsh && npm ci && npm run typecheck && npm run build)
+```
+
+## Conventions
+
+- **JSON on stdout, diagnostics on stderr.** Every command prints one JSON
+  object (or JSON lines) so an agent can consume it. Keep the exit codes stable:
+  `0` ok, `2` usage/permission/platform, `3` not found or upstream error,
+  `4` capture failed, `5` target changed.
+- **Never claim success you did not verify.** Emitted-the-event (`action_sent`)
+  and the-UI-changed (`verified`) are separate facts, and every fallback hint
+  must follow from evidence.
+- **No machine-specific defaults.** No absolute paths, no assumed display scale,
+  no assumed app names. If a value depends on the machine, detect it or require
+  it explicitly.
+- **Pure logic stays pure.** Policy functions such as `jev.decide()` take values
+  and return a decision, so they can be unit-tested without a desktop or a
+  network.
+- **Both bridges stay bridges.** The pi and dsh packages call the CLI with argv
+  arrays and return its output; they must not grow a second implementation, and
+  they must never use a shell string.
+- **Keep the skill honest.** If a capability changes, update `skill/SKILL.md` —
+  it is what agents actually read. `packages/pi/skills/...` mirrors it.
+
+## Adding a command
+
+1. Implement it in the matching `src/macos_computer_use/*.py` module.
+2. Wire it into `build_parser()` in `cli.py` and into the `doctor` hints if it
+   needs a permission.
+3. Add or extend a test when the logic is pure.
+4. Update `README.md`, `skill/SKILL.md`, and (for a new desktop action) both
+   bridge packages' tool lists.
+
+## Reporting a computer-use bug
+
+Include: the exact command, the JSON it returned, the app and its bundle id, the
+macOS version, and whether the app was frontmost. If AX targeting failed, say
+whether `verified` was false and whether the element is custom-drawn — that is
+the difference between a bug here and an app that does not implement
+accessibility.
+
+## License
+
+By contributing you agree your work is released under the MIT License.

macos_computer_use_kit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sur-Cai
+
+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.

macos_computer_use_kit-0.2.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.5
+Name: macos-computer-use-kit
+Version: 0.2.0
+Summary: AX-first computer-use toolkit for AI agents on macOS: accessibility-tree targeting, process-scoped input, clipboard-safe paste, action read-back verification, visual feedback, and optional Jev semantic guards.
+Project-URL: Homepage, https://github.com/Sur-Cai/macos-computer-use-kit
+Project-URL: Repository, https://github.com/Sur-Cai/macos-computer-use-kit
+Project-URL: Issues, https://github.com/Sur-Cai/macos-computer-use-kit/issues
+License: MIT License
+        
+        Copyright (c) 2026 Sur-Cai
+        
+        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: accessibility,agent-tools,ai-agent,automation,computer-use,dsh-plugin,macos,opencode,pi-package
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: MacOS X :: Cocoa
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Requires-Dist: pillow>=10.0
+Requires-Dist: pyobjc-framework-applicationservices>=10.0; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-cocoa>=10.0; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-quartz>=10.0; sys_platform == 'darwin'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# macos-computer-use-kit
+
+**AX-first computer use for AI agents on macOS.** Instead of screenshot → eyeball
+coordinates → click and hope, read the accessibility tree, get each element's
+semantics and exact geometry, act on it, then verify the action actually changed
+the UI.
+
+A small, composable toolkit: accessibility-tree targeting, process- and
+window-scoped input, clipboard-safe pasting, action read-back verification,
+blank-frame detection, visual feedback, and optional Jev (TypeSafe System One)
+semantic guards.
+
+Works with any agent that can run a shell command, and ships first-class
+packages for [pi](#pi) and [DeepSeek Harness](#deepseek-harness-dsh).
+
+## Why
+
+These mechanisms were distilled from three mature implementations rather than
+invented from scratch:
+
+| Source | Mechanism absorbed |
+| --- | --- |
+| Codex CUA (`@oai/cua` / Sky service) | AX state + element index, `setValue`, batch actions, event delivery via `CGEventPostToPid` |
+| ZCode Computer Use | `*_to_window` window-scoped input, `target_changed` validation, clipboard-safe paste pipeline, `screenshot_blank` |
+| Grok Bot (`CUGrokBotService`) | snapshots with stable element ids + text budget + drill-down, action read-back, coordinate fallback on failure |
+
+## Install
+
+macOS 12+, Python 3.10+.
+
+```bash
+pip install macos-computer-use-kit        # or: pipx install macos-computer-use-kit
+macos-cu doctor                           # check permissions, displays, dependencies
+
+# from a checkout (editable install + agent skill)
+git clone https://github.com/Sur-Cai/macos-computer-use-kit && cd macos-computer-use-kit
+./install.sh
+```
+
+Grant both permissions to the process that runs the agent (your terminal, or the
+agent app). `macos-cu doctor` reports what is missing and where to enable it:
+
+- **Accessibility** — AX reads, `AXPress`, `setValue`, posted events
+- **Screen Recording** — `shot` (without it every capture is black)
+
+## Quickstart
+
+```bash
+# semantic targeting: exact geometry, zero visual reasoning
+macos-cu ax find --app com.apple.finder --role AXButton --title Size
+macos-cu ax tree --app com.apple.finder --depth 16 --max 200
+
+# token-efficient snapshot with stable ids, trimmed to a budget
+macos-cu ax snapshot --app com.apple.finder --budget 1200 --file /tmp/ax.json
+macos-cu ax resolve  --file /tmp/ax.json --id 0.1.0.6.0.0.0.0.5.8
+
+# native AX action + read-back verification
+macos-cu ax press --app com.apple.finder --role AXButton --title Size
+# {"verified":true,"state_changed":true,...}
+
+# window-scoped input: the user's cursor never moves, target is validated
+macos-cu input windows --app "Google Chrome"
+macos-cu input click --window-id 12345 --x 171 --y 28 --show
+macos-cu input click --window-id 12345 --x 171 --y 28 --expect "37040:12345:642:244:824:640"
+# mismatch -> {"ok":false,"reason":"target_changed"} and exit code 5
+
+# clipboard-safe paste (saves and restores the user's clipboard)
+macos-cu paste --app com.google.Chrome --text "你好" --mode pid
+
+# screenshot with blank-frame detection
+macos-cu shot capture --app "Google Chrome" --out /tmp/shot.png
+macos-cu shot check --file /tmp/shot.png
+```
+
+## CLI
+
+One binary, JSON output, stable exit codes (`0` ok, `2` usage/permission,
+`3` not found, `4` capture failed, `5` target changed).
+
+| Group | Commands |
+| --- | --- |
+| `macos-cu ax` | `tree`, `find`, `click-info`, `snapshot`, `resolve`, `press`, `setvalue` |
+| `macos-cu input` | `windows`, `cursor`, `pid`, `click`, `key`, `scroll`, `move` |
+| `macos-cu paste` | clipboard-safe paste (`--mode pid\|hid`, `--keep`) |
+| `macos-cu shot` | `capture`, `check`, `windows` |
+| `macos-cu overlay` | `show`, `clear` |
+| `macos-cu jev` | `guard`, `select` (optional, JSON on stdin) |
+| `macos-cu doctor` | permissions, displays, dependencies, Jev setup |
+
+### Coordinate spaces
+
+| Space | Source | Used by |
+| --- | --- | --- |
+| `screen[x, y]` | AX/CoreGraphics points, origin at the primary display's top-left | `input --x --y`, `overlay` |
+| window-relative | element point − window origin | `input click --window-id N --x --y` |
+| `shot[x, y]` | `center_screen × --shot-scale` | only for harnesses whose screenshots are scaled differently from screen points; there is deliberately no default |
+
+Secondary displays placed left of or above the primary produce **negative**
+coordinates. That is normal. `macos-cu doctor` prints the layout.
+
+## Agent integrations
+
+| Harness | What you get | Install |
+| --- | --- | --- |
+| any agent with a shell | the full CLI | `pip install macos-computer-use-kit` |
+| [opencode](https://opencode.ai) | skill `macos-computer-use` (auto-discovered) | `./install.sh` |
+| [pi](https://pi.dev) | skill + 9 native tools | `pi install npm:pi-macos-computer-use` |
+| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | plugin bundle, 5 tools | `dsh plugin --profile <name> add dsh-macos-computer-use` |
+
+<a name="pi"></a>
+### pi package
+
+`packages/pi` — `pi-macos-computer-use` (npm, `pi-package` keyword). Registers
+`macos_cu_doctor`, `macos_ax_find`, `macos_ax_press`, `macos_input_windows`,
+`macos_input_click`, `macos_input_key`, `macos_paste`, `macos_shot`,
+`macos_jev_guard`. Every tool shells out with an argv array (`shell: false`), so
+model-supplied text can never reach a shell.
+
+```bash
+pi install npm:pi-macos-computer-use
+pi -e ./packages/pi        # try it for one run without installing
+```
+
+App launchers do not inherit your interactive shell's `PATH`. If the CLI is
+installed but pi cannot find it, set `MACOS_CU_BIN=/abs/path/to/macos-cu` and
+restart pi (the dsh plugin honours the same variable).
+
+<a name="deepseek-harness-dsh"></a>
+### DeepSeek Harness plugin
+
+`packages/dsh` — `dsh-macos-computer-use`, a Cordis bundle
+(`dsh.bundle.patch` → `cordis.patch.yml`). Registers `macos_cu_doctor`,
+`macos_ax_find`, `macos_ax_press`, `macos_input_click`, `macos_shot`.
+
+```bash
+dsh plugin --profile demo add dsh-macos-computer-use
+dsh --profile demo --dump-config    # verify the layer before booting
+```
+
+It deliberately does **not** claim the exclusive `ctx.computerUse` provider slot:
+it adds tools rather than owning desktop operations, so it cannot block the
+in-box Cua Driver provider. See `packages/dsh/README.md`.
+
+### opencode skill
+
+`./install.sh` installs `skill/SKILL.md` to
+`~/.config/opencode/skills/macos-computer-use/`, where opencode discovers it
+automatically.
+
+## The four capabilities that matter
+
+**1. Window-scoped input with target validation.** Events are posted straight to
+the target process (`CGEventPostToPid`), so the physical cursor never moves and
+the user can keep working. `--expect pid:wid:x:y:w:h` refuses to act when the
+window moved or lost focus since you looked at it.
+
+**2. Native AX actions with read-back verification.** `press`/`setvalue` compare
+the window's visible-text fingerprint and focused element before and after, and
+report `verified` separately from `action_sent`. When AX cannot act (custom-drawn
+UI), the result carries a `hint` telling you to fall back to a coordinate click
+or a clipboard paste — you find out from evidence, not from guessing.
+
+**3. Clipboard safety.** The user's clipboard is saved before and restored after.
+Takeover and non-consumption are reported explicitly, so pasting CJK text never
+silently destroys what the user had copied.
+
+**4. Never reason on a blank frame.** `shot` classifies captures as
+`ok` / `all_black` / `all_white` / `uniform` with a hint, so a missing permission
+or an occluded window is reported instead of hallucinated UI state.
+
+## Design principles
+
+1. **AX-first.** Semantic + exact geometry beats visual inference. Screenshots
+   verify; they do not target.
+2. **`action_sent` ≠ `verified`.** Keep "we emitted the event" and "the UI
+   changed" as separate facts.
+3. **The clipboard is a shared resource.** Save, detect interference, restore.
+4. **Targets must be explicit and checkable.** Window input carries a signature;
+   a mismatch is `target_changed`, not a misclick.
+5. **Small models judge, code decides.** Jev returns calibrated probabilities;
+   thresholds and side effects stay in code. Cost ladder: deterministic code
+   (µs) < Jev (~1 s) < visual reasoning (seconds to tens of seconds).
+6. **Make it visible.** Action points draw a ring, so the user is never watching
+   a black box.
+
+## Jev semantic guards (optional)
+
+The only part that needs a key. Everything else works without it.
+
+```bash
+echo '{"task":"send the report to Alice",
+       "expected":{"recipient":"Alice","message":"Q3 numbers"},
+       "observed":{"chat_title":"Bob","input_text":"Q3 numbers"}}' | macos-cu jev guard
+# {"answers":{"right_target":0.02,"input_ok":0.98,"blocker":"wrong_target"},
+#  "decision":"switch_target"}
+```
+
+One request fans out independent judgments and **code** applies the policy:
+proceed only when `blocker=none` and both probabilities clear the threshold; the
+model may only suggest the two safe recoveries (`switch_target`, `retype_input`);
+anything else asks the user. `macos-cu jev select` picks one candidate element
+with a `none` escape hatch and a confidence gate.
+
+Key: `TYPESAFE_API_KEY` or `~/.config/typesafe/api_key`
+(<https://console.typesafe.ai/keys>). Pin `TYPESAFE_MODEL` for automation;
+`jev-latest` is the friendly default. Question-design guidance lives in
+[`skill/reference/jev-best-practices.md`](skill/reference/jev-best-practices.md).
+
+## Known limitations
+
+- macOS only (AX, CGEvent, ScreenCaptureKit are macOS APIs).
+- Custom-drawn UIs (some Electron apps, games, chat apps) expose shallow or
+  uncooperative AX trees. Fall back to screenshots **after** read-back fails,
+  not before.
+- Process-targeted key events are accepted by most apps but not all: browsers
+  usually accept background keystrokes; some chat apps require the app to be
+  frontmost for typing and pasting.
+- AX coordinate scale is display-dependent. `center_shot` is opt-in via
+  `--shot-scale` for exactly this reason.
+- The user may be using the machine at the same time. Concurrent automation is
+  risky; one extra verification before an irreversible action is cheap.
+
+## Repository layout
+
+```
+src/macos_computer_use/   the CLI implementation (pip-installable)
+tools/*.py                compatibility shims -> the same modules
+skill/                    agent skill (SKILL.md + Jev reference)
+packages/pi/              pi package (skill + native tools)
+packages/dsh/             DeepSeek Harness plugin bundle
+install.sh                local installer (venv + CLI + skill + Jev key)
+tests/                    unit tests for the safety-relevant logic
+```
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the
+conventions (JSON on stdout, stable exit codes, no machine-specific defaults).
+Release steps and catalog-listing criteria live in
+[PUBLISHING.md](PUBLISHING.md); notable changes are in
+[CHANGELOG.md](CHANGELOG.md).
+
+## 中文说明
+
+给 AI agent 用的 macOS 电脑控制工具箱：**AX 语义定位**（不靠截图目测坐标）、
+进程/窗口级输入（物理光标不动）、剪贴板安全粘贴、动作回读校验、空白帧检测、
+可视反馈，以及可选的 Jev 语义护栏。
+
+```bash
+pip install macos-computer-use-kit
+macos-cu doctor          # 检查辅助功能 / 屏幕录制权限、显示器、依赖、Jev
+```
+
+Agent 集成：`./install.sh`（opencode skill）、`pi install npm:pi-macos-computer-use`（pi）、
+`dsh plugin --profile <名> add dsh-macos-computer-use`（DeepSeek Harness）。
+完整流程与避坑见 [`skill/SKILL.md`](skill/SKILL.md)。
+
+## License
+
+MIT

macos_computer_use_kit-0.2.0/PUBLISHING.md

@@ -0,0 +1,109 @@
+# Publishing this toolkit
+
+Three artifacts can be published from this repository, all versioned in lockstep
+with the CLI (`0.2.0` today):
+
+| Artifact | Registry | Command |
+| --- | --- | --- |
+| `macos-computer-use-kit` | PyPI | `python -m build && twine upload dist/*` |
+| `pi-macos-computer-use` | npm | `cd packages/pi && npm publish` |
+| `dsh-macos-computer-use` | npm | `cd packages/dsh && npm publish` |
+
+## Before the first publish
+
+1. **Never commit a key.** The Jev key lives in `~/.config/typesafe/api_key` and
+   the environment. Check `git status` and `git diff --cached` before pushing;
+   `.gitignore` already excludes `node_modules/`, build output, and `*.png`.
+2. **Bump all three versions together.** They are independent manifests:
+   `pyproject.toml`, `packages/pi/package.json`, `packages/dsh/package.json`.
+   `packages/pi/skills/macos-computer-use/SKILL.md` is a copy of `skill/SKILL.md`
+   — refresh it (`cp skill/SKILL.md packages/pi/skills/macos-computer-use/SKILL.md`)
+   and re-run `./install.sh` to refresh the opencode copy.
+3. **Add GitHub topics** for discoverability (Repository → About → Topics):
+
+   ```
+   dsh-plugin  pi-package  macos  computer-use  accessibility
+   ai-agents  agent-skills  gui-automation  opencode
+   ```
+
+   `dsh-plugin` is how <https://github.com/topics/dsh-plugin> indexes plugins;
+   the `pi-package` npm keyword is what <https://pi.dev/packages> indexes.
+
+## PyPI (the CLI)
+
+```bash
+python -m pip install --upgrade build twine
+python -m build                       # sdist + wheel in dist/
+twine check dist/*
+twine upload dist/*                   # needs a PyPI API token
+```
+
+Verify the install path in a clean venv before tagging:
+
+```bash
+python -m venv /tmp/verify && /tmp/verify/bin/pip install dist/*.whl
+/tmp/verify/bin/macos-cu doctor
+```
+
+## npm: the pi package
+
+```bash
+cd packages/pi
+npm run typecheck
+npm pack --dry-run                    # confirm the tarball contents
+npm publish                           # unscoped; use --access public inside a scope
+```
+
+The `pi` manifest (`extensions`, `skills`) plus the `pi-package` keyword are what
+make the catalog pick it up. The extension is loaded through pi's TypeScript
+loader, so it ships sources — no build step, and `peerDependencies` stay `"*"`.
+
+## npm: the dsh bundle
+
+```bash
+cd packages/dsh
+npm run build                         # emits lib/ ; `prepare` runs this on git installs
+npm pack --dry-run
+npm publish
+```
+
+The bundle contract is `dsh.bundle.patch` → `cordis.patch.yml`. Because git
+installs fetch **sources**, the `prepare` script must stay self-contained (no
+monorepo project references); publishing a tarball or npm package ships the
+built `lib/` and needs no build permission from the user.
+
+Users install with:
+
+```bash
+dsh plugin --profile <name> add dsh-macos-computer-use        # from npm (recommended)
+dsh plugin --profile <name> add ./dsh-macos-computer-use-0.2.0.tgz   # from a packed tarball
+```
+
+The npm and tarball forms ship the prebuilt `lib/`, so no build permission is
+needed. Installing straight from git fetches sources and runs `prepare`, which
+pnpm blocks until the user allowlists it — and because the bundle lives in
+`packages/dsh/` of this monorepo, the git form is only convenient for a repo
+that root-mounts the package. Prefer npm or the tarball for distribution.
+
+## Catalog listings
+
+- **pi**: publishing to npm is enough — the gallery at <https://pi.dev/packages>
+  lists packages tagged `pi-package`. Optionally add a `pi.image` or
+  `pi.video` preview to `packages/pi/package.json` for a richer card.
+- **dsh**: add the `dsh-plugin` GitHub topic, then open a PR against
+  [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+  (their bar: installs with `dsh plugin add`, does what its one-line description
+  says, right category, maintained). There is also
+  [dsh-market](https://github.com/dsh-market/dsh-market) for in-app discovery.
+
+## Release checklist
+
+```bash
+./install.sh                      # local sanity: CLI + skill
+macos-cu doctor                   # permissions still granted after reinstalling
+(cd packages/pi  && npm run typecheck)
+(cd packages/dsh && npm run typecheck && npm run build)
+```
+
+Then tag (`git tag v0.2.0 && git push --tags`) and publish the artifacts you
+intend to ship.