simt-dev 0.2.0__py3-none-any.whl

python/simt_dev/__init__.py

@@ -0,0 +1,32 @@
+"""simt-dev, installed from PyPI.
+
+The package this wheel ships is a Node program. See {@link simt_dev.cli} for
+what this file is for and why it works the way it does; nothing here needs to
+be remembered twice.
+"""
+
+from .cli import find_node, main, vendored_root
+
+__all__ = ["main", "find_node", "vendored_root", "__version__"]
+
+
+def _version():
+    """The version of the vendored tool, read from its own manifest.
+
+    Not from this wheel's distribution metadata. The two are asserted equal by
+    a test, and reading the vendored one here is what makes a disagreement
+    visible to a reader: `simt --version` reporting the bytes that actually
+    shipped, rather than a number that was correct at packaging time.
+    """
+    import json
+    import os
+
+    path = os.path.join(vendored_root(), "package.json")
+    try:
+        with open(path, encoding="utf-8") as handle:
+            return json.load(handle)["version"]
+    except (OSError, ValueError, KeyError):
+        return None
+
+
+__version__ = _version()

python/simt_dev/cli.py

@@ -0,0 +1,225 @@
+"""The ``simt`` command, installed from PyPI.
+
+simt-dev is a Node program. It has zero runtime dependencies and it does not
+need a build step, which means the whole thing is a directory of `.mjs` files
+and a `package.json` - about 1.3 MB of text. So the wheel carries those bytes
+directly, alongside this file, and the only question left is *which node runs
+them*.
+
+That question is the whole content of {@link find_node}, and it is asked in an
+order rather than answered with a guess:
+
+    SIMT_DEV_NODE          an explicit override, for anyone who wants to say
+    nodejs_wheel           the bundled node, if the [node] extra was installed
+    PATH                   whatever node this machine already has
+
+and then a refusal, not a fallback to something invented. A placeholder node
+path is worse than no path: it produces "file not found" from a depth that has
+nothing to do with the problem, when the problem is that node is not installed
+and the reader can fix that in one command.
+
+This file is also why the process is *replaced* rather than *spawned*.
+``os.execv`` hands the file descriptors over, so terminal width, a tty, stdin,
+Ctrl-C, and the exit code all arrive unchanged. A subprocess wrapper has to
+reimplement every one of those, and the day one of them is forgotten is the day
+somebody's editor-integrated ``simt`` loses its colours.
+"""
+
+import os
+import shutil
+import sys
+
+__all__ = ["main", "find_node", "vendored_root"]
+
+# The env var that names a node binary. SIMT_DEV_NODE rather than SIMT_DEV_BIN,
+# because SIMT_DEV_BIN already means something and means it well: it names the
+# *tool* (an executable, or a .mjs entry point to hand to node), and the hook
+# shims and the CI workflow both read it. This names the *runtime*. Two names
+# for two questions; reusing one would make the value's meaning depend on which
+# of the two files is reading it.
+ENV_NODE = "SIMT_DEV_NODE"
+
+# The env var that names the program to run instead of the one this wheel ships.
+# Same meaning it has in the shim: a path to a .mjs entry point, so somebody
+# working on simt-dev itself can `pip install -e .` and still point at their
+# checkout without editing anything.
+ENV_BIN = "SIMT_DEV_BIN"
+
+BIN_REL = os.path.join("bin", "simt-dev.mjs")
+
+
+def vendored_root():
+    """The directory this wheel placed the tool's own source in.
+
+    Resolved from ``__file__``, because that is the one location that is correct
+    in a checkout, in a wheel, in a virtualenv and in a system install alike. A
+    path derived from the current working directory would be wrong the moment
+    a hook ran this from inside a repository - which is the normal case.
+
+    One level up from this file, not two: this module is `simt_dev/cli.py` and
+    the vendored tree sits beside it at `simt_dev/vendored/`. (It was written as
+    two while the package layout was still a guess, and the symptom was an
+    install that worked and a command that reported its own wheel as
+    incomplete.)
+    """
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), "vendored")
+
+
+def _executable(candidate):
+    """Whether `candidate` names a file this user may execute."""
+    return candidate is not None and os.path.isfile(candidate) and os.access(candidate, os.X_OK)
+
+
+def _from_env():
+    """`SIMT_DEV_NODE`, as a path or as a name to look up.
+
+    Accepted in both spellings because the reader who sets it has one in mind: a
+    Homebrew prefix or an nvm path is a path, and `node` is a name. Deciding by
+    the presence of a separator is the usual way this is done and the wrong test
+    to be clever about - `./node` and `node` are both things people type.
+    """
+    value = os.environ.get(ENV_NODE)
+    if not value:
+        return None
+    if os.sep in value or (os.altsep and os.altsep in value):
+        return value if _executable(value) else None
+    return shutil.which(value)
+
+
+def _from_bundled():
+    """The node that ships with the `[node]` extra, if that extra is installed.
+
+    Imported lazily and guarded, because the default install does not have it:
+    `pip install simt-dev` must not pay for, or fail on, an optional wheel it
+    did not ask for. An ImportError here means "no bundled node", which is an
+    ordinary outcome and not an error to report.
+    """
+    try:
+        import nodejs_wheel  # noqa: PLC0415  the whole point is that it may be absent
+    except Exception:
+        return None
+    try:
+        return nodejs_wheel.node()
+    except Exception:
+        # Present but unusable - a broken install, a platform with no wheel.
+        # Reported rather than swallowed by returning a path that does not run.
+        return None
+
+
+def _from_path():
+    """Whatever node this machine already has.
+
+    `shutil.which` rather than a list of well-known install directories. A
+    hardcoded `/opt/homebrew/bin/node` list is three guesses and a surprise:
+    it starts preferring a guess over the reader's own PATH, and it is already
+    out of date for anyone who installs node differently.
+    """
+    return shutil.which("node")
+
+
+def find_node(env=None):
+    """The node binary that should run the tool, or None if there is not one.
+
+    The order is load-bearing and not aesthetic. An explicit override wins, so
+    a reader who has a reason can say so. The bundled node comes next rather
+    than before `PATH`, because a machine that already has node should keep
+    using the node it uses everywhere else - installing the `[node]` extra on
+    such a machine is meant to add a fallback, not to silently switch the
+    runtime underneath an otherwise-working setup.
+
+    @param env an environment mapping; defaults to `os.environ`
+    @returns {str|None} a path to a node binary, or None
+    """
+    env = os.environ if env is None else env
+
+    explicit = env.get(ENV_NODE)
+    if explicit:
+        candidate = _from_env()
+        if candidate is not None:
+            return candidate
+        # Falling through on a bad override would run a *different* node than
+        # the one asked for, which is the one outcome worse than failing.
+        sys.stderr.write(
+            f"simt: {ENV_NODE} names {explicit!r}, which is not an executable node.\n"
+            f"  set {ENV_NODE} to a node binary or a name on PATH, or unset it to let simt find one.\n"
+        )
+        return None
+
+    bundled = _from_bundled()
+    if bundled is not None:
+        return bundled
+
+    return _from_path()
+
+
+def _program(vendored):
+    """Which `.mjs` entry point to run, honouring SIMT_DEV_BIN the way the shim does."""
+    override = os.environ.get(ENV_BIN)
+    if override:
+        if " " in override:
+            # The shim's rule, kept: the value names one program. A value with a
+            # space in it is either a command line, which there is no safe way to
+            # split here, or a genuine path with a space in it - and refusing
+            # both costs nothing, while accepting the first is a shell injection.
+            sys.stderr.write(
+                f"simt: {ENV_BIN} names a command line, not a program.\n"
+                f"  set it to a single executable or a .mjs path, e.g.\n"
+                f"    {ENV_BIN}=/path/to/checkout/bin/simt-dev.mjs\n"
+            )
+            return None
+        return override if override.endswith(".mjs") else None
+    return os.path.join(vendored, BIN_REL)
+
+
+def _remedy():
+    """What to do about the missing node, in a form the reader can act on.
+
+    The `[node]` extra first because it is the one remedy that is the same
+    command on every platform. Platform package managers are deliberately not
+    listed: `apt`, `dnf`, `pacman` and `brew` differ, getting one wrong is
+    itself a broken remedy, and a wrong remedy is a second problem stacked on
+    the first - which is the failure this project's rules exist to prevent.
+    """
+    return (
+        "  REMEDY: pip install simt-dev[node]   (installs a bundled node, and works on every platform)\n"
+        "          or install Node.js yourself and make sure `node` is on PATH\n"
+        "          or set SIMT_DEV_NODE=/path/to/node"
+    )
+
+
+def main(argv=None):
+    """Replace this process with `node <entry point> <args>`.
+
+    @param argv arguments to forward; defaults to `sys.argv[1:]` so an explicit
+      caller gets a slash list while an installed entry point gets the shell's
+    @returns {int} only ever 2 (an error before exec); otherwise this does not return
+    """
+    argv = sys.argv[1:] if argv is None else argv
+
+    node = find_node()
+    if node is None:
+        sys.stderr.write(
+            "simt: cannot find node, which is the runtime this tool is written in.\n"
+            f"{_remedy()}\n"
+        )
+        return 2
+
+    vendored = vendored_root()
+    program = _program(vendored)
+    if program is None:
+        # `_program` has already said which env var was wrong and how.
+        return 2
+    if not os.path.isfile(program):
+        sys.stderr.write(
+            f"simt: {program} is not in this installation.\n"
+            "  this usually means the wheel is incomplete - reinstall with:\n"
+            "    pip install --force-reinstall --no-cache-dir simt-dev\n"
+        )
+        return 2
+
+    os.execv(node, [node, program, *argv])
+    raise AssertionError("unreachable: execv does not return")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

simt_dev/__init__.py

@@ -0,0 +1,32 @@
+"""simt-dev, installed from PyPI.
+
+The package this wheel ships is a Node program. See {@link simt_dev.cli} for
+what this file is for and why it works the way it does; nothing here needs to
+be remembered twice.
+"""
+
+from .cli import find_node, main, vendored_root
+
+__all__ = ["main", "find_node", "vendored_root", "__version__"]
+
+
+def _version():
+    """The version of the vendored tool, read from its own manifest.
+
+    Not from this wheel's distribution metadata. The two are asserted equal by
+    a test, and reading the vendored one here is what makes a disagreement
+    visible to a reader: `simt --version` reporting the bytes that actually
+    shipped, rather than a number that was correct at packaging time.
+    """
+    import json
+    import os
+
+    path = os.path.join(vendored_root(), "package.json")
+    try:
+        with open(path, encoding="utf-8") as handle:
+            return json.load(handle)["version"]
+    except (OSError, ValueError, KeyError):
+        return None
+
+
+__version__ = _version()

simt_dev/cli.py

@@ -0,0 +1,225 @@
+"""The ``simt`` command, installed from PyPI.
+
+simt-dev is a Node program. It has zero runtime dependencies and it does not
+need a build step, which means the whole thing is a directory of `.mjs` files
+and a `package.json` - about 1.3 MB of text. So the wheel carries those bytes
+directly, alongside this file, and the only question left is *which node runs
+them*.
+
+That question is the whole content of {@link find_node}, and it is asked in an
+order rather than answered with a guess:
+
+    SIMT_DEV_NODE          an explicit override, for anyone who wants to say
+    nodejs_wheel           the bundled node, if the [node] extra was installed
+    PATH                   whatever node this machine already has
+
+and then a refusal, not a fallback to something invented. A placeholder node
+path is worse than no path: it produces "file not found" from a depth that has
+nothing to do with the problem, when the problem is that node is not installed
+and the reader can fix that in one command.
+
+This file is also why the process is *replaced* rather than *spawned*.
+``os.execv`` hands the file descriptors over, so terminal width, a tty, stdin,
+Ctrl-C, and the exit code all arrive unchanged. A subprocess wrapper has to
+reimplement every one of those, and the day one of them is forgotten is the day
+somebody's editor-integrated ``simt`` loses its colours.
+"""
+
+import os
+import shutil
+import sys
+
+__all__ = ["main", "find_node", "vendored_root"]
+
+# The env var that names a node binary. SIMT_DEV_NODE rather than SIMT_DEV_BIN,
+# because SIMT_DEV_BIN already means something and means it well: it names the
+# *tool* (an executable, or a .mjs entry point to hand to node), and the hook
+# shims and the CI workflow both read it. This names the *runtime*. Two names
+# for two questions; reusing one would make the value's meaning depend on which
+# of the two files is reading it.
+ENV_NODE = "SIMT_DEV_NODE"
+
+# The env var that names the program to run instead of the one this wheel ships.
+# Same meaning it has in the shim: a path to a .mjs entry point, so somebody
+# working on simt-dev itself can `pip install -e .` and still point at their
+# checkout without editing anything.
+ENV_BIN = "SIMT_DEV_BIN"
+
+BIN_REL = os.path.join("bin", "simt-dev.mjs")
+
+
+def vendored_root():
+    """The directory this wheel placed the tool's own source in.
+
+    Resolved from ``__file__``, because that is the one location that is correct
+    in a checkout, in a wheel, in a virtualenv and in a system install alike. A
+    path derived from the current working directory would be wrong the moment
+    a hook ran this from inside a repository - which is the normal case.
+
+    One level up from this file, not two: this module is `simt_dev/cli.py` and
+    the vendored tree sits beside it at `simt_dev/vendored/`. (It was written as
+    two while the package layout was still a guess, and the symptom was an
+    install that worked and a command that reported its own wheel as
+    incomplete.)
+    """
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), "vendored")
+
+
+def _executable(candidate):
+    """Whether `candidate` names a file this user may execute."""
+    return candidate is not None and os.path.isfile(candidate) and os.access(candidate, os.X_OK)
+
+
+def _from_env():
+    """`SIMT_DEV_NODE`, as a path or as a name to look up.
+
+    Accepted in both spellings because the reader who sets it has one in mind: a
+    Homebrew prefix or an nvm path is a path, and `node` is a name. Deciding by
+    the presence of a separator is the usual way this is done and the wrong test
+    to be clever about - `./node` and `node` are both things people type.
+    """
+    value = os.environ.get(ENV_NODE)
+    if not value:
+        return None
+    if os.sep in value or (os.altsep and os.altsep in value):
+        return value if _executable(value) else None
+    return shutil.which(value)
+
+
+def _from_bundled():
+    """The node that ships with the `[node]` extra, if that extra is installed.
+
+    Imported lazily and guarded, because the default install does not have it:
+    `pip install simt-dev` must not pay for, or fail on, an optional wheel it
+    did not ask for. An ImportError here means "no bundled node", which is an
+    ordinary outcome and not an error to report.
+    """
+    try:
+        import nodejs_wheel  # noqa: PLC0415  the whole point is that it may be absent
+    except Exception:
+        return None
+    try:
+        return nodejs_wheel.node()
+    except Exception:
+        # Present but unusable - a broken install, a platform with no wheel.
+        # Reported rather than swallowed by returning a path that does not run.
+        return None
+
+
+def _from_path():
+    """Whatever node this machine already has.
+
+    `shutil.which` rather than a list of well-known install directories. A
+    hardcoded `/opt/homebrew/bin/node` list is three guesses and a surprise:
+    it starts preferring a guess over the reader's own PATH, and it is already
+    out of date for anyone who installs node differently.
+    """
+    return shutil.which("node")
+
+
+def find_node(env=None):
+    """The node binary that should run the tool, or None if there is not one.
+
+    The order is load-bearing and not aesthetic. An explicit override wins, so
+    a reader who has a reason can say so. The bundled node comes next rather
+    than before `PATH`, because a machine that already has node should keep
+    using the node it uses everywhere else - installing the `[node]` extra on
+    such a machine is meant to add a fallback, not to silently switch the
+    runtime underneath an otherwise-working setup.
+
+    @param env an environment mapping; defaults to `os.environ`
+    @returns {str|None} a path to a node binary, or None
+    """
+    env = os.environ if env is None else env
+
+    explicit = env.get(ENV_NODE)
+    if explicit:
+        candidate = _from_env()
+        if candidate is not None:
+            return candidate
+        # Falling through on a bad override would run a *different* node than
+        # the one asked for, which is the one outcome worse than failing.
+        sys.stderr.write(
+            f"simt: {ENV_NODE} names {explicit!r}, which is not an executable node.\n"
+            f"  set {ENV_NODE} to a node binary or a name on PATH, or unset it to let simt find one.\n"
+        )
+        return None
+
+    bundled = _from_bundled()
+    if bundled is not None:
+        return bundled
+
+    return _from_path()
+
+
+def _program(vendored):
+    """Which `.mjs` entry point to run, honouring SIMT_DEV_BIN the way the shim does."""
+    override = os.environ.get(ENV_BIN)
+    if override:
+        if " " in override:
+            # The shim's rule, kept: the value names one program. A value with a
+            # space in it is either a command line, which there is no safe way to
+            # split here, or a genuine path with a space in it - and refusing
+            # both costs nothing, while accepting the first is a shell injection.
+            sys.stderr.write(
+                f"simt: {ENV_BIN} names a command line, not a program.\n"
+                f"  set it to a single executable or a .mjs path, e.g.\n"
+                f"    {ENV_BIN}=/path/to/checkout/bin/simt-dev.mjs\n"
+            )
+            return None
+        return override if override.endswith(".mjs") else None
+    return os.path.join(vendored, BIN_REL)
+
+
+def _remedy():
+    """What to do about the missing node, in a form the reader can act on.
+
+    The `[node]` extra first because it is the one remedy that is the same
+    command on every platform. Platform package managers are deliberately not
+    listed: `apt`, `dnf`, `pacman` and `brew` differ, getting one wrong is
+    itself a broken remedy, and a wrong remedy is a second problem stacked on
+    the first - which is the failure this project's rules exist to prevent.
+    """
+    return (
+        "  REMEDY: pip install simt-dev[node]   (installs a bundled node, and works on every platform)\n"
+        "          or install Node.js yourself and make sure `node` is on PATH\n"
+        "          or set SIMT_DEV_NODE=/path/to/node"
+    )
+
+
+def main(argv=None):
+    """Replace this process with `node <entry point> <args>`.
+
+    @param argv arguments to forward; defaults to `sys.argv[1:]` so an explicit
+      caller gets a slash list while an installed entry point gets the shell's
+    @returns {int} only ever 2 (an error before exec); otherwise this does not return
+    """
+    argv = sys.argv[1:] if argv is None else argv
+
+    node = find_node()
+    if node is None:
+        sys.stderr.write(
+            "simt: cannot find node, which is the runtime this tool is written in.\n"
+            f"{_remedy()}\n"
+        )
+        return 2
+
+    vendored = vendored_root()
+    program = _program(vendored)
+    if program is None:
+        # `_program` has already said which env var was wrong and how.
+        return 2
+    if not os.path.isfile(program):
+        sys.stderr.write(
+            f"simt: {program} is not in this installation.\n"
+            "  this usually means the wheel is incomplete - reinstall with:\n"
+            "    pip install --force-reinstall --no-cache-dir simt-dev\n"
+        )
+        return 2
+
+    os.execv(node, [node, program, *argv])
+    raise AssertionError("unreachable: execv does not return")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

simt_dev/vendored/CHANGELOG.md

@@ -0,0 +1,166 @@
+# Changelog
+
+All notable changes to this package are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — 2026-10-11
+
+### Publishable from PyPI and Homebrew as well as npm
+
+simt-dev is a *repository* tool, and the people who adopt a repository are not
+all Node developers. Somebody running `simt init` inside a repository with no
+`package.json` has no reason to install a package manager, and a Homebrew user
+has no reason to install Node to install a tool that needs Node.
+
+So it now publishes to three channels, from one version number:
+
+```sh
+npm i -D simt-dev        # a tarball of .mjs files
+pip install simt-dev      # a wheel carrying those same bytes
+brew install QuazarMedia/tap/simt-dev
+```
+
+The wheel is not a wrapper around `npm install`. It carries the tool's own
+source, and `scripts/verify-wheel.mjs` builds both artefacts and hashes every
+file in both — a release fails when a single byte differs between them. That
+check exists because the obvious defect in this arrangement is the wheel and the
+tarball quietly shipping different code.
+
+`simt` is the one command, on every channel. Where node comes from is
+`SIMT_DEV_NODE`, then the bundled node from `pip install "simt-dev[node]"`,
+then `node` on `PATH` — and if none of those resolve you get the remedy rather
+than a placeholder path. There are no required dependencies on any channel.
+*(ADR-058)*
+
+The channels are published in a fixed order rather than in parallel, and the
+reason is not taste: the Homebrew formula downloads the npm tarball at install
+time, so a formula naming a version still sitting in npm's staging area
+installs a 404. Both jobs fail with that stated, and are run again after
+`npm stage approve`.
+
+## [0.1.1] — 2026-10-11
+
+### A foreign hook on an event this repo does not gate is chained
+
+`0.1.0` chained the wrong set of hooks and is worth replacing rather than
+recommending. It chained on the event *vocabulary* — anything that was not
+`pre-commit` or `pre-push` — when the question worth asking is whether **this
+repository** declares a gate for that event.
+
+The difference is `simt-app`, whose `pre-push` is `git-lfs`. `pre-push` is an
+event this tool gates in general, so `0.1.0` displaced that hook; and because
+`simt-app` declares no `pre-push` gate there was no shim for the event either, so
+git would have found no `pre-push` hook at all. LFS objects would have stopped
+being uploaded, with nothing to notice it — the exact silent failure chaining
+exists to prevent, reached by fixing the wrong half of it.
+
+`0.1.1` asks the manifest. An event the repo declares a gate for is left to
+`gates.commands`, where the hook runs as a gate and its verdict appears in the
+report; every other foreign hook is chained. That also picks up
+`simt-landing`'s Lighthouse pre-push, which declares no gates at all.
+*(ADR-018, as amended)*
+
+Upgrade with `npm i -D simt-dev@0.1.1`, then `simt hooks install --yes`. Any
+repository already routed with `0.1.0` should re-run it: the shims it writes
+will differ where a gated event was previously displaced.
+
+## [0.1.0] — 2026-10-11
+
+The first release with real contents in it. `1.0.0` was an empty reservation of the name
+and `0.0.0-stage` was its rehearsal; neither shipped a byte anyone could run, so this entry
+is the whole history. The decisions behind it are readable in the package under
+`docs/decisions/`, and from any checkout with `simt rules why <id>`.
+
+### The command is `simt`
+
+The package is `simt-dev` and the command is `simt`. They are not the same thing and were
+never required to be: the command appears only in text the tool itself writes, and that
+text migrates on the next write. The package name, the `.simt-hooks/` directory and the
+`simt-dev-check.yml` gate already exist in every repository that adopted this tool, and
+they did not move. The manifest and the region markers did — see below.
+
+### The manifest is `simt.json`
+
+The manifest was called `simt-dev.json`; it is now `simt.json`. The move is a
+read-both/write-new, so nothing in an adopting repository has to be done:
+
+- Every read takes `simt.json` if it exists, else `simt-dev.json`, so a repository that
+  has not written since the upgrade is still seen as adopted.
+- Every write goes to `simt.json`, and a lone `simt-dev.json` is moved, not shadowed.
+- The old name keeps working until the first `init` or manifest write in each repository,
+  and that write closes it. *(ADR-056)*
+
+### The region markers are `simt:`
+
+The generated region was stamped `<!-- simt-dev:begin -->` / `<!-- simt-dev:end -->` — and
+so was the provenance header inside it; every one of those lines is now `simt:`. The move
+is the same read-both/write-new as the manifest:
+
+- Every read accepts either spelling, so a repository that has not written since the
+  upgrade is still seen as adopted.
+- Every write emits `simt:` only, so the first `sync` in each repository migrates its
+  regions in place, and that write closes the window.
+- A file holding two regions — one of each spelling — is a state only a hand edit can
+  make, and it is reported malformed rather than merged. *(ADR-056)*
+
+### A hook you already had keeps running
+
+`hooks install` points `core.hooksPath` at `.simt-hooks/`, and git reads **every** hook from
+that one directory — not just the two events this tool gates. So adopting a repository that
+had its own `post-commit`, `post-checkout` or `post-merge` would have quietly stopped them:
+nothing fails, nothing is logged, and the hook is still on disk looking intact.
+
+Those hooks are now **chained**. Install writes a shim for them that runs the repository's
+own hook and forwards git's arguments, so nothing is lost and the reason is in the file. If
+the hook is gone, the shim refuses and names the path instead of passing quietly. A hook on
+an event this tool *does* gate (`pre-commit`, `pre-push`) is deliberately not chained —
+declare it under `gates.commands` so the dispatcher runs it and its verdict appears in the
+gate report. *(ADR-018, as amended)*
+
+### What a first release has to say out loud
+
+These are the behaviours a reader is most likely to trip over. Each one is deliberate,
+and each has a numbered decision record behind it — but a behaviour nobody can discover
+without reading the source is not a documented one.
+
+- **`sync` and `init` write nothing without `--yes`.** Both print a plan and exit. `sync`
+  exits **1** when the plan is non-empty, so bare `sync` doubles as a check. Neither ever
+  commits or pushes. *(ADR-035, ADR-036)*
+- **`upgrade` moves a pin and nothing else.** It never adopts a repository, never repairs
+  one, and never rewrites a manifest. Every consumer moves to the same version as one set.
+- **A pre-commit hook with no reachable binary fails closed.** The refusal is the correct
+  behaviour, not a bug; the remedy it prints is the command that obtains one.
+  *(ADR-010, ADR-018)*
+- **A gate whose tool is not installed is dropped, with a remedy naming the package.**
+  It is never declared and silently unrunnable. *(ADR-017)*
+- **Two rules are never loaded twice.** Each rule projects to exactly one place, chosen by
+  what the harness actually reads. *(ADR-021, ADR-046)*
+- **macOS and Linux only.** Windows `npm i` fails with npm's `EBADPLATFORM`, which npm
+  will not let a package explain; use WSL2. See the platform section of the README.
+  *(ADR-012)*
+
+### Packaging
+
+- Licence set to Apache-2.0; the `LICENSE` file is the canonical, unmodified text.
+- `files` no longer lists `skills`, `agents`, `tooling` or `hooks`, none of which exist,
+  and no longer ships `docs/plans`. The tarball is the tool and the decisions behind it,
+  and nothing else.
+- The package `description` no longer names an internal ecosystem. It is the first line
+  anybody outside the project reads.
+- Unscoped, so the install command is `npm i -D simt-dev` rather than a name under an
+  organisation. The `@simt` and `@quazarmedia` scopes were both free; an unscoped name is
+  the one a reader can guess.
+
+### Notes for anyone upgrading a hook
+
+A shim installed by an earlier version looks for `SIMT_DEV_BIN`, then for
+`node_modules/simt-dev/bin/simt-dev.mjs`, then for a program named `simt` on `PATH`. The
+last of those is new, so a machine that installed the package before this release and
+never ran `simt hooks install` again will find nothing until the dependency is refreshed
+and `simt hooks install --yes` is re-run. That is a real upgrade step and it is called out
+here rather than discovered.
+
+[0.2.0]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.2.0
+[0.1.1]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.1.1
+[0.1.0]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.1.0