@guidanti/duet 0.0.0-stage → 0.0.1

package/LICENSE.md

@@ -0,0 +1,51 @@
+# Licence
+
+Copyright © 2026 Guidanti Inc. All rights reserved.
+
+**duet is not open-source software, and no licence to use it is granted here.** These terms reserve every right in duet that applicable law and the terms of the services hosting it leave to reserve. Permission to use duet is granted to a named person or organisation in writing, individually, and in no other way -- see [how permission is granted](#3-how-permission-is-granted). Being able to download duet is not permission to use it.
+
+Nothing in this file is an SPDX open-source licence, a permissive licence, a non-commercial licence or a "source-available" licence. The npm package declares `UNLICENSED`, which is npm's own spelling for "no licence is granted here", and that declaration is accurate rather than provisional.
+
+## 1. What is covered
+
+"duet" means the software in this repository and every artifact built from it: the Python package, the deterministic wheel and its record, the generated `@guidanti/duet` npm package, the prompt templates, the rule files and fragments, the provider schemas, the documentation and the tests. It does not mean your own projects, your own task documents, or the reports and evidence duet writes into your repository when you run it; those are yours.
+
+## 2. What publication does and does not grant
+
+Publishing duet where anyone can fetch it is a distribution decision. It is not a licence, and the two are separate deliberately.
+
+- **On GitHub, nothing is published at all.** The repository `guidanti/duet` is private and stays private, so the viewing-and-forking licence [GitHub's Terms of Service](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#5-license-grant-to-other-users) grant to other users -- which is a condition of setting a repository to be viewed publicly -- never arises here. What the private repository keeps is the repository: its history, its branches, its tests, its tooling, its documentation, and the release pages, notes and assets a publication creates there, none of which can be read or downloaded without access to it.
+- **duet's own Python code is distributed, in the public package.** The npm package below carries the built wheel, and a wheel of a pure-Python package is readable source: anybody who installs `@guidanti/duet` has the `.py` modules duet runs, together with these terms and [NOTICE.md](NOTICE.md), and needs no GitHub account to get them. Being able to read duet is not permission to use it, and it is not permission to copy, adapt or redistribute it either -- what reserves the rights in that code is this file, not the difficulty of obtaining it.
+- **On npm.** Publishing `@guidanti/duet` licenses npm to provide the package to users of npm's services and to copy, publish and analyse it, under [npm's Open Source Terms](https://docs.npmjs.com/policies/open-source-terms/#your-content). Those terms leave it to the publisher to decide whether and how to license the content to anyone else. This file is that decision: nothing is licensed to anyone else. Installing the package, or having a copy of it on your machine, is not permission to use it.
+- **Everywhere else.** No other distribution, redistribution, mirroring, republication, sublicensing or bundling of duet is permitted without a written grant.
+
+## 3. How permission is granted
+
+Permission is an individual, written grant from Guidanti Inc. naming the person or organisation it is for, the version or versions it covers, and what it permits. Ask at **min@guidanti.com**; the template is in [permission to use duet](docs/licensing.md), and it is governed by the laws of Ontario, Canada. A grant is not implied by a download, an installation, an invoice, a conversation, a fork, a GitHub star, an issue, a pull request or the absence of an objection. Guidanti Inc. may decline a request without reason.
+
+Contributions are internal to Guidanti Inc.: there is no inbound contributor licence or assignment, and a contribution from anyone else is not accepted.
+
+## 4. What these terms do not claim
+
+Stating a reservation of rights is not a claim to control everything adjacent to duet, and this file claims none of the following:
+
+- **Independent reimplementation is unaffected.** Copyright protects this expression of duet, not the idea of a two-agent review loop, not the design it embodies, not a workflow, not a command vocabulary and not an interface as such. Anyone may build their own software that does what duet does, including after reading the documentation, and these terms neither prohibit it nor are intended to deter it.
+- **Rights the law does not let a licence remove stay where they are.** Fair use and fair dealing, the interoperability and error-correction rights mandatory law reserves to a lawful user, and every other non-waivable statutory exception apply whatever this file says. Where applicable law is narrower than a clause here, that clause is limited to what the law permits and the rest stands.
+- **No patent, trademark or service-mark licence is granted, and none is asserted against you** by this file.
+- **Nothing here restricts discussing, reviewing, criticising or writing about duet.**
+
+## 5. External software
+
+duet bundles no third-party code. It needs a Python interpreter, Git and the vendor CLIs it drives, and it installs, bundles and redistributes none of them -- see [NOTICE.md](NOTICE.md) for what that means for each of them and whose terms govern them.
+
+## 6. No warranty, and no liability
+
+duet is provided "as is", without warranty of any kind, express or implied, including the implied warranties of merchantability, fitness for a particular purpose and non-infringement. duet drives external agent CLIs that run commands and change files with your permissions, and it spends money at your providers; you are responsible for what it is pointed at. To the fullest extent applicable law permits, Guidanti Inc. is not liable for any claim, damage, data loss, provider charge or other liability arising from duet or its use. A written grant may state terms of its own, and where it does, those terms govern between its parties.
+
+## 7. Contact
+
+Licensing enquiries: **min@guidanti.com**. [Permission to use duet](docs/licensing.md) is the longer account of the same route.
+
+---
+
+**Review status: approved.** This wording was **revised on 2026-10-08** to carry the owner's decisions -- the repository stays private, Guidanti Inc. owns the existing code, Ontario and Canada govern the grant, contributions are internal only, and min@guidanti.com is the published contact -- and **corrected the same day**, because clause 2 described the private repository as meaning duet's source is not distributed and the public package's wheel is readable Python source. The owner was shown those corrected terms and **approved them on 2026-10-08**, naming the exact bytes: sha256 `41d8a0763b603eafe24d5d9605167299bfc03d52cd01c9add56c8b5a843ad9e7` for this file and `23f7ea74c9f7afc9c96baaf268136b73200fc9f8d0937ba92f5991cee1726d10` for [NOTICE.md](NOTICE.md). Clauses 1 to 7 above are unchanged by this note and are the approved text; what changed after the approval is this paragraph, which is why the file no longer hashes to the digest the approval names. A change to any clause would be a new approval and a different build identity. No publication has happened.

package/NOTICE.md

@@ -0,0 +1,35 @@
+# Notices
+
+Copyright © 2026 Guidanti Inc. All rights reserved. The terms are in [LICENSE.md](LICENSE.md); this file is the third-party notice that travels beside them.
+
+## duet bundles no third-party code
+
+Every byte duet distributes is its own. The wheel holds the `duet` package and its own metadata and nothing else: `pyproject.toml` declares an empty dependency list, the test suite re-derives that list from the package's own imports so adding a dependency fails there rather than quietly becoming part of the installation, and `duet install --artifact` refuses an artifact that declares any `Requires-Dist` at all. The generated `@guidanti/duet` npm package is assembled from an explicit allowlist -- a launcher, an install script, a bootstrap, that same wheel, its record, a generated manifest and README, and these notices -- with no dependencies and nothing taken from a checkout. Nothing is downloaded by an installation of duet, at any point.
+
+So there is no vendored library here, no statically linked component, and no accompanying licence text that a redistribution would have to carry. If that ever changes, the component and its terms belong in this file and in the packaging allowlists that carry it.
+
+## What duet needs, and does not distribute
+
+duet runs external programs. It installs none of them, bundles none of them, redistributes none of them and modifies none of them; each is obtained by you, from its own publisher, under that publisher's own terms, and nothing in [LICENSE.md](LICENSE.md) says anything about them.
+
+| Program | What duet does with it | Whose terms govern |
+| --- | --- | --- |
+| CPython (3.9 or newer) | a managed runtime is a virtual environment built from an interpreter already on your machine, which stays where it is and is recorded as a dependency | the Python Software Foundation's, or whoever packaged the interpreter you installed |
+| Git | duet asks it where the project is, creates the implementation worktree with it and integrates through it | the Git project's |
+| Codex CLI (`codex`) | launched as a subprocess, per turn | OpenAI's |
+| Claude Code (`claude`) | launched as a subprocess, per turn | Anthropic's |
+| Node and npm | install and update duet, and nothing afterwards; no duet command invokes either | the Node.js project's and npm's |
+
+Your use of those programs, and what your provider accounts permit, is between you and them. duet starts no sign-in, opens no credential file and makes no claim about which account a CLI would run as.
+
+## Contributor tooling, which is not distributed
+
+The root `package.json` is private contributor metadata named `duet`, is marked `"private": true` and is never published. Its one development dependency, `@changesets/cli` 3.0.3, is recorded in `package-lock.json` as MIT-licensed, is installed from the registry by a contributor who needs it, and is not part of any artifact duet distributes: it is absent from the wheel, absent from the generated npm package's allowlist, and never read at runtime.
+
+## The agents' own output
+
+duet drives model providers, and what a provider's model writes into a report, a prompt or your repository arrives under that provider's terms. Guidanti Inc. makes no claim to it and gives no assurance about it.
+
+---
+
+**Review status: approved.** Revised with [LICENSE.md](LICENSE.md) on 2026-10-08 under the owner's decisions and **approved the same day**, by sha256 `23f7ea74c9f7afc9c96baaf268136b73200fc9f8d0937ba92f5991cee1726d10`, which is this file as it stood when the approval was recorded. Everything above this note is the approved text and is unchanged by it; this paragraph is what moved the digest afterwards. Nothing else in this file has ever changed: duet still bundles no third-party code, so the decisions about distribution, jurisdiction, contributions and contact touch the terms rather than the notices. The account of the approval is in [permission to use duet](docs/licensing.md#what-the-owner-decided-and-what-that-settled).

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @guidanti/duet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An automated Codex <-> Claude research, planning and implementation loop.
+
+npm installs and updates duet. It does not run it: the `duet` on your PATH is a shell script that execs the managed dispatcher, and every invocation after that is Python. Nothing duet runs invokes Node, npm or a source checkout.
+
+## Prerequisite: a Python you already have
+
+duet needs CPython >=3.9 on macOS (arm64) and does not install one. Installation finds an interpreter already on the machine, checks its version, architecture and ability to create a virtual environment, and fails with instructions when nothing usable is there. The official installers are at https://www.python.org/downloads/macos/.
+
+## Install, update, retry
+
+```sh
+npm install --global @guidanti/duet
+```
+
+Setup runs in this package's install script: it verifies the bundled artifact, installs it as an immutable managed runtime under `~/.duet/installations/`, self-checks that runtime, writes the dispatcher and selects the new build when the default is this distribution's own or there is none. Running the same command again is the retry and the upgrade; it installs beside what is there and removes nothing.
+
+`DUET_SETUP_PYTHON=/path/to/python3` names the interpreter yourself. `--foreground-scripts` shows the setup output. If npm is configured with `ignore-scripts`, no setup runs and the launcher says so.
+
+## Uninstalling is not removing your runtimes
+
+```sh
+npm uninstall --global @guidanti/duet
+```
+
+That removes this package and the `duet` npm linked onto your PATH. It removes nothing under `~/.duet`: every managed runtime, pin, run and piece of evidence stays, reachable by each runtime's own launcher path and by the dispatcher at `~/.duet/installations/.dispatch/duet`. Removing a runtime is `duet remove <name> --yes`, one build at a time, and it refuses while anything still needs it. duet never purges `~/.duet`.
+
+## This build
+
+- version `0.0.1`, build `c921cf37ea5b416b`
+- artifact `duet-0.0.1-py3-none-any.whl`
+- `sha256=560d88ba5bca6f3c7d17573a17659cef2763208acad085ebb43d26306c713f64`
+
+## Permission to use duet
+
+duet is not open-source software and installing it is not permission to use it: the copyright is Guidanti Inc.'s, all rights are reserved, and permission is granted individually and in writing. `license` is `UNLICENSED`, which is npm's own spelling for "no license is granted here" and is accurate rather than provisional. The terms are `LICENSE.md` and `NOTICE.md` in this package; the source repository is private, so ask for permission at min@guidanti.com rather than looking for an issue tracker.
+
+`docs/packaging.md` and `docs/launching.md` are the full documentation, in that private repository; this README and the files beside it are what travels with the package.

package/artifact/duet-0.0.1.artifact.json

@@ -0,0 +1,15 @@
+{
+  "build_id": "c921cf37ea5b416b",
+  "name": "duet",
+  "schema": 1,
+  "source": {
+    "clean": true,
+    "commit": "807ed6c5ca2f004f25160b072f82f59e2046466b"
+  },
+  "verification": {
+    "contract": 1
+  },
+  "version": "0.0.1",
+  "wheel": "duet-0.0.1-py3-none-any.whl",
+  "wheel_sha256": "560d88ba5bca6f3c7d17573a17659cef2763208acad085ebb43d26306c713f64"
+}

package/bin/duet

@@ -0,0 +1,64 @@
+#!/bin/sh
+# Generated by duet.npm for @guidanti/duet 0.0.1.
+#
+# This is the whole of what npm puts on your PATH. It invokes no
+# Node, no npm and no source checkout: it finds the managed
+# dispatcher under the installation root and becomes it, and from
+# there duet is Python. The dispatcher reads which build a run is
+# pinned to -- so an existing run reaches the build it was started
+# on, whatever this package was upgraded to since.
+set -u
+launcher=$0
+while [ -L "$launcher" ]; do
+  directory=$(CDPATH= cd -P "$(dirname "$launcher")" && pwd)
+  target=$(readlink "$launcher")
+  case "$target" in
+    /*) launcher=$target ;;
+    *) launcher=$directory/$target ;;
+  esac
+done
+here=$(CDPATH= cd -P "$(dirname "$launcher")/.." && pwd)
+root=${DUET_INSTALL_ROOT:-$HOME/.duet/installations}
+dispatcher=$root/.dispatch/duet
+if [ ! -x "$dispatcher" ]; then
+  cat >&2 <<SETUP
+duet: this installation of @guidanti/duet has no managed runtime yet.
+  There is no dispatcher at $dispatcher.
+  Setup runs in this package's install script, so if npm was run
+  with --ignore-scripts, or that script failed, nothing was
+  installed and nothing was selected.
+  Install or retry:      npm install --global @guidanti/duet
+  See why it failed:     npm install --global @guidanti/duet --foreground-scripts
+  Run setup by hand:     /bin/sh $here/lib/setup.sh
+  duet installs no software by itself: nothing has been downloaded,
+  installed or selected here.
+SETUP
+  exit 1
+fi
+# Whether a finished setup under this root installed the artifact
+# *this* package carries. One digest, matched in the record setup
+# writes last, with shell builtins and no interpreter: the launcher
+# is on the path of every duet invocation.
+set_up_here() {
+  [ -f "$1" ] || return 1
+  while IFS= read -r line; do
+    case "$line" in
+      *'"wheel_sha256": "560d88ba5bca6f3c7d17573a17659cef2763208acad085ebb43d26306c713f64"'*) return 0 ;;
+    esac
+  done < "$1"
+  return 1
+}
+if ! set_up_here "$root/npm.json"; then
+  cat >&2 <<INCOMPLETE
+duet: @guidanti/duet 0.0.1 is installed and its setup did not finish.
+  The runtime this package carries is not under $root, so this
+  command runs the managed runtime that is already there. Every run
+  still reaches the build it was started on, and nothing has been
+  downloaded, installed or selected -- including by this message.
+  Retry the setup:       npm install --global @guidanti/duet
+  See why it failed:     npm install --global @guidanti/duet --foreground-scripts
+  If scripts are off:    npm config get ignore-scripts
+  Run setup by hand:     /bin/sh $here/lib/setup.sh
+INCOMPLETE
+fi
+exec "$dispatcher" "$@"

package/duet-npm.json

@@ -0,0 +1,33 @@
+{
+  "artifact": {
+    "build_id": "c921cf37ea5b416b",
+    "sidecar": "duet-0.0.1.artifact.json",
+    "verification": {
+      "contract": 1
+    },
+    "wheel": "duet-0.0.1-py3-none-any.whl",
+    "wheel_sha256": "560d88ba5bca6f3c7d17573a17659cef2763208acad085ebb43d26306c713f64"
+  },
+  "contents": {
+    "LICENSE.md": "b4d64972a2579e709434fab1e11cd0c7cf936d8ced6240af164a8283b3c1f2d7",
+    "NOTICE.md": "95e6b3212b7a907e59befdca37999fd683cf02c94cc2d487df62b77c7c3ef2ba",
+    "README.md": "d58cc9bde1fb0583d1c51f33a59affb6f0359ab0f0c0196aeef3be0bddb40b00",
+    "artifact/duet-0.0.1-py3-none-any.whl": "560d88ba5bca6f3c7d17573a17659cef2763208acad085ebb43d26306c713f64",
+    "artifact/duet-0.0.1.artifact.json": "a4a69d90f3aa1fc7cae414136822aa48a170b5acd97a30ea14ed181d93a24cdc",
+    "bin/duet": "521c73f89306e0060376f3afd4ea2de3c5eba9a299d9b8a3bacaba40a4078f6b",
+    "lib/setup.py": "af8b06ef8c81a9c41e75a9b1d2f34da9633773199201776811d95e073e6917ab",
+    "lib/setup.sh": "98e180d851b626898d1a71ad0794b17b8c2496e6907368ab0ac40180832f7494",
+    "package.json": "6a00de1294ab0aec1a03cdc715e13f988d48d7509e7bd49261669338fe34928d"
+  },
+  "notices": [
+    "LICENSE.md",
+    "NOTICE.md"
+  ],
+  "package": "@guidanti/duet",
+  "schema": 1,
+  "source": {
+    "clean": true,
+    "commit": "807ed6c5ca2f004f25160b072f82f59e2046466b"
+  },
+  "version": "0.0.1"
+}

package/lib/setup.py

@@ -0,0 +1,70 @@
+"""Generated by duet.npm for @guidanti/duet 0.0.1.
+
+The install script's Python half: check the bundled artifact against
+the digest this file was generated with, import the installer out of
+those same bytes, and run it. Nothing here verifies an artifact
+itself, creates an environment, or writes outside the installation
+root the installer resolves."""
+
+import hashlib
+import os
+import sys
+
+PACKAGE = '@guidanti/duet'
+PACKAGE_VERSION = '0.0.1'
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+WHEEL = os.path.join(HERE, 'artifact', 'duet-0.0.1-py3-none-any.whl')
+SIDECAR = os.path.join(HERE, 'artifact', 'duet-0.0.1.artifact.json')
+WHEEL_SHA256 = '560d88ba5bca6f3c7d17573a17659cef2763208acad085ebb43d26306c713f64'
+
+
+def refuse(message, *lines):
+    sys.stderr.write('duet: ' + message + '\n')
+    for line in lines:
+        sys.stderr.write(('  ' + line if line else '') + '\n')
+    return 1
+
+
+def main():
+    try:
+        with open(WHEEL, 'rb') as stream:
+            data = stream.read()
+    except OSError as exc:
+        return refuse(
+            'the artifact this package carries could not be read ('
+            + str(exc) + ')',
+            'Nothing was installed and nothing was selected.',
+            'Install the package again:  npm install --global @guidanti/duet')
+    found = hashlib.sha256(data).hexdigest()
+    if found != WHEEL_SHA256:
+        return refuse(
+            'the artifact this package carries is not the one it was'
+            ' published with',
+            'expected sha256=' + WHEEL_SHA256,
+            'found    sha256=' + found,
+            '',
+            'duet will not install bytes that are not the bytes this'
+            ' package records.',
+            'Nothing was installed and nothing was selected.',
+            'Install the package again:  npm install --global @guidanti/duet')
+    # Those bytes, and nothing else, are what the installer is read
+    # out of. A wheel is a zip and an interpreter imports from one
+    # directly, so there is no temporary environment to clean up.
+    sys.path.insert(0, WHEEL)
+    try:
+        from duet import npm
+    except Exception as exc:
+        return refuse(
+            'the artifact this package carries could not be read as'
+            ' a duet (' + type(exc).__name__ + ': ' + str(exc)
+            + ')',
+            'Nothing was installed and nothing was selected.',
+            'Install the package again:  npm install --global @guidanti/duet')
+    return npm.setup_main(wheel=WHEEL, sidecar=SIDECAR, here=HERE,
+                          package=PACKAGE,
+                          package_version=PACKAGE_VERSION,
+                          argv=sys.argv[1:])
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/setup.sh

@@ -0,0 +1,116 @@
+#!/bin/sh
+# Generated by duet.npm for @guidanti/duet 0.0.1.
+#
+# npm runs this once, after it has unpacked the package. It finds an
+# interpreter that can run the installer and hands over to it; the
+# installer is the bundled artifact's own code, and it is what checks
+# the version, the architecture and the capabilities of whichever
+# interpreter a runtime will actually be built from.
+set -u
+here=$(CDPATH= cd -P "$(dirname "$0")/.." && pwd)
+
+resolved() {
+  # The pathname a candidate really is, every link followed. A case
+  # check on the name alone is not enough: an ordinary alias in
+  # somebody's ~/bin pointing at the macOS stub *is* the stub, and
+  # duet must not execute it to find that out.
+  target=$1
+  hops=0
+  while [ -L "$target" ] && [ "$hops" -lt 40 ]; do
+    directory=$(CDPATH= cd -P "$(dirname "$target")" 2>/dev/null && pwd) || return 1
+    link=$(readlink "$target") || return 1
+    case "$link" in
+      /*) target=$link ;;
+      *) target=$directory/$link ;;
+    esac
+    hops=$((hops + 1))
+  done
+  directory=$(CDPATH= cd -P "$(dirname "$target")" 2>/dev/null && pwd) || return 1
+  case "$directory" in
+    /) printf '/%s\n' "$(basename "$target")" ;;
+    *) printf '%s/%s\n' "$directory" "$(basename "$target")" ;;
+  esac
+}
+
+runnable() {
+  # Never these: on macOS /usr/bin/python3 is a stub that execs
+  # xcrun, and running it with the command line tools absent opens
+  # the operating system's own installation dialog. duet starts no
+  # installer, so it does not ask. Asked of the name *and* of what
+  # the name resolves to, before anything is executed.
+  case "$1" in
+    /usr/bin/python3|/usr/bin/python) return 1 ;;
+  esac
+  real=$(resolved "$1") || return 1
+  case "$real" in
+    /usr/bin/python3|/usr/bin/python) return 1 ;;
+  esac
+  [ -x "$1" ] || return 1
+  # It has to run, and it has to be new enough to read the installer:
+  # an interpreter below duet's floor cannot import the bundled
+  # artifact at all, and 'that is not a duet' is the wrong diagnosis
+  # for 'that Python is too old'.
+  "$1" -I -c 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else 1)' >/dev/null 2>&1 || return 1
+  return 0
+}
+
+found=
+if [ -n "${DUET_SETUP_PYTHON:-}" ]; then
+  if runnable "$DUET_SETUP_PYTHON"; then
+    found=$DUET_SETUP_PYTHON
+  else
+    cat >&2 <<OVERRIDE
+duet: DUET_SETUP_PYTHON names $DUET_SETUP_PYTHON, which duet will not run as an interpreter.
+  It is not there, it is not executable, it did not run, it is older than CPython >=3.9, or it is a stub duet does not ask.
+  duet needs CPython >=3.9 on macOS (arm64), able to create a virtual environment.
+  Install Python from https://www.python.org/downloads/macos/
+  An explicit interpreter is an instruction, so duet does not look elsewhere when it is unusable.
+  Nothing was installed and nothing was selected. Unset it or name another, then run:
+    npm install --global @guidanti/duet
+OVERRIDE
+    exit 1
+  fi
+fi
+if [ -z "$found" ]; then
+  for candidate in \
+      python3.14 \
+      python3.13 \
+      python3.12 \
+      python3.11 \
+      python3.10 \
+      python3.9 \
+      python3 \
+      /opt/homebrew/opt/python@3.14/bin/python3.14 \
+      /opt/homebrew/opt/python@3.13/bin/python3.13 \
+      /opt/homebrew/opt/python@3.12/bin/python3.12 \
+      /opt/homebrew/opt/python@3.11/bin/python3.11 \
+      /opt/homebrew/opt/python@3.10/bin/python3.10 \
+      /opt/homebrew/opt/python@3.9/bin/python3.9 \
+      /Library/Frameworks/Python.framework/Versions/3.14/bin/python3.14 \
+      /Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13 \
+      /Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12 \
+      /Library/Frameworks/Python.framework/Versions/3.11/bin/python3.11 \
+      /Library/Frameworks/Python.framework/Versions/3.10/bin/python3.10 \
+      /Library/Frameworks/Python.framework/Versions/3.9/bin/python3.9 \
+      /Library/Developer/CommandLineTools/usr/bin/python3 \
+      ; do
+    case "$candidate" in
+      /*) path=$candidate ;;
+      *) path=$(command -v "$candidate" 2>/dev/null) || path= ;;
+    esac
+    [ -n "$path" ] || continue
+    if runnable "$path"; then found=$path; break; fi
+  done
+fi
+if [ -z "$found" ]; then
+  cat >&2 <<'NOPYTHON'
+duet: no usable Python was found, and duet does not install one.
+  duet needs CPython >=3.9 on macOS (arm64), able to create a virtual environment.
+  Install Python from https://www.python.org/downloads/macos/
+  Then run:  npm install --global @guidanti/duet
+  Or name one yourself:  DUET_SETUP_PYTHON=/path/to/python3 npm install --global @guidanti/duet
+  Nothing was installed, nothing was selected, and no existing duet installation was changed.
+NOPYTHON
+  exit 1
+fi
+exec "$found" -I "$here/lib/setup.py" "$@"

package/package.json

@@ -1,6 +1,27 @@
 {
+  "bin": {
+    "duet": "bin/duet"
+  },
+  "cpu": [
+    "arm64"
+  ],
+  "description": "An automated Codex <-> Claude research, planning and implementation loop.",
+  "files": [
+    "bin/",
+    "lib/",
+    "artifact/",
+    "duet-npm.json",
+    "LICENSE.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "license": "UNLICENSED",
   "name": "@guidanti/duet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "os": [
+    "darwin"
+  ],
+  "scripts": {
+    "postinstall": "/bin/sh lib/setup.sh"
+  },
+  "version": "0.0.1"
+}