entropy-machines 0.1.1

package/bin/status

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""status — print live factory state. Reads; writes nothing.
+
+    bin/status
+
+Three questions, answered from the tracker and the docs directory:
+
+    what is ready to work on        (bin/tracker ready)
+    what is in flight               (DISPATCH notes with no HANDOFF yet)
+    which docs have open questions  (unanswered .response boxes)
+
+It is a READ. Nothing here files, claims, dispatches or edits — so it is safe
+to run at the top of any session, on a shared checkout, or in a loop.
+
+This is the one surviving half of what used to be `bin/adopt prime`, the body
+of a Claude Code SessionStart hook that bin/adopt installed into
+.claude/settings.json. That whole mechanism — a hashed managed block written
+into someone else's instruction file, a consent prompt, a settings.json edit,
+per-runner profiles — is gone. The PRINTING is what was actually worth having,
+and it is worth having as a command a human or an agent can just run.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+
+# ENTROPY_MACHINES_HOME is the harness DIRECTORY — where bin/tracker sits — which may be
+# the repo root or a subdirectory of it. Not a root and not a separate repo;
+# see lib/roots.sh.
+ENTROPY_MACHINES_HOME = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.join(ENTROPY_MACHINES_HOME, "lib"))
+import config  # noqa: E402  -- needs ENTROPY_MACHINES_HOME on the path first
+
+
+def entropy_machines_root():
+    """Mirrors lib/roots.sh's entropy_machines_root(): the repository's main checkout,
+    or None. `git rev-parse --git-common-dir` -- NOT --show-toplevel, which
+    prints a linked WORKTREE's own path; .entropy/ is gitignored and absent
+    from every worktree, so that would report an empty tracker as "0 ready"
+    rather than as an error. Falls back to walking up for config.json when
+    there is no git."""
+    try:
+        p = subprocess.run(
+            ["git", "rev-parse", "--git-common-dir"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        p = None
+    if p is not None and p.returncode == 0 and p.stdout.strip():
+        common = p.stdout.strip()
+        if not os.path.isabs(common):
+            common = os.path.join(os.getcwd(), common)
+        return os.path.realpath(os.path.join(common, os.pardir))
+    d = os.getcwd()
+    while True:
+        if os.path.exists(os.path.join(d, "config.json")):
+            return d
+        parent = os.path.dirname(d)
+        if parent == d:
+            return None
+        d = parent
+
+
+def docs_dir_for(root):
+    """config.json's docs.dir, defaulting to entropy-machines-docs -- the same
+    default bin/init writes to and bin/serve reads from. Never raises."""
+    try:
+        with open(os.path.join(ENTROPY_MACHINES_HOME, "config.json"), encoding="utf-8") as f:
+            cfg = json.load(f)
+        d = (cfg.get("docs") or {}).get("dir")
+        if isinstance(d, str) and d.strip():
+            return d.strip().strip("/")
+    except Exception:
+        pass
+    return "entropy-machines-docs"
+
+
+def scan_unanswered_docs(root):
+    """Best-effort: dialogue docs in this harness's convention mark each
+    question with <div class="response" data-resp="KEY"> and record answers in
+    a <script id="responses-data"> JSON blob (see bin/serve,
+    lib/doc-template.html). Returns [(path, unanswered_count), ...] for docs
+    with at least one unanswered question. Never raises -- a doc this cannot
+    parse is skipped."""
+    # THE CONFIGURED DOCS DIRECTORY. bin/init installs the orientation PRD into
+    # docs.dir and bin/serve serves it from there; this must agree with both.
+    docs = os.path.join(root, docs_dir_for(root))
+    if not os.path.isdir(docs):
+        return []
+    out = []
+    resp_re = re.compile(r'class="response"[^>]*data-resp="([^"]+)"')
+    data_re = re.compile(r'<script[^>]*id="responses-data"[^>]*>(.*?)</script>', re.DOTALL)
+    for fname in sorted(os.listdir(docs)):
+        if not fname.endswith(".html"):
+            continue
+        path = os.path.join(docs, fname)
+        try:
+            with open(path, encoding="utf-8") as f:
+                content = f.read()
+            # Strip HTML comments first. lib/doc-template.html's own header
+            # comment contains a literal data-resp example -- counting it made
+            # every doc built from the template report one phantom question
+            # nobody could ever answer, so a fully-answered doc kept nagging.
+            content = re.sub(r"<!--[\s\S]*?-->", "", content)
+            keys = set(resp_re.findall(content))
+            if not keys:
+                continue
+            m = data_re.search(content)
+            answered = set()
+            if m:
+                try:
+                    answered = {k for k, v in json.loads(m.group(1)).items() if str(v).strip()}
+                except (json.JSONDecodeError, AttributeError):
+                    pass
+            unanswered_n = len(keys - answered)
+            if unanswered_n:
+                out.append((path, unanswered_n))
+        except OSError:
+            continue
+    return out
+
+
+def main(argv):
+    if argv and argv[0] in ("-h", "--help"):
+        print(__doc__.strip("\n"))
+        return 0
+    if argv:
+        print("usage: bin/status", file=sys.stderr)
+        return 2
+
+    config.refuse_nested_clone("status")
+    root = entropy_machines_root()
+    if not root or not os.path.isfile(os.path.join(ENTROPY_MACHINES_HOME, "config.json")):
+        print("entropy-machines: not configured here -- run %s/bin/init" % ENTROPY_MACHINES_HOME)
+        return 0
+
+    tracker = os.path.join(ENTROPY_MACHINES_HOME, "bin", "tracker")
+
+    def run_tracker(args):
+        try:
+            p = subprocess.run(
+                [tracker] + args, cwd=root, capture_output=True, text=True, timeout=15,
+            )
+        except (OSError, subprocess.SubprocessError):
+            return None
+        if p.returncode != 0:
+            return None
+        return p.stdout
+
+    ready_out = run_tracker(["ready"])
+    if ready_out is None:
+        print("entropy-machines: tracker unavailable (bin/tracker ready failed)")
+    else:
+        ready = []
+        for line in ready_out.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                ready.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        if ready:
+            print("entropy-machines: %d issue(s) ready -- `bin/tracker ready`" % len(ready))
+            for i in ready[:10]:
+                print("  %s  %s" % (i.get("id", "?"), i.get("title") or i.get("summary") or ""))
+            if len(ready) > 10:
+                print("  ... and %d more" % (len(ready) - 10))
+        else:
+            print("entropy-machines: 0 issues ready")
+
+    notes_out = run_tracker(["notes"])
+    if notes_out is not None:
+        state = {}
+        for line in notes_out.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            issue = rec.get("issue")
+            if not issue:
+                continue
+            verb = rec.get("verb")
+            if verb == "DISPATCH":
+                state[issue] = "dispatched"
+            elif verb == "HANDOFF":
+                state[issue] = "handed_off"
+        in_flight = [i for i, st in state.items() if st == "dispatched"]
+        if in_flight:
+            print("entropy-machines: %d issue(s) in flight (dispatched, not yet handed off): %s"
+                  % (len(in_flight), ", ".join(sorted(in_flight))))
+
+    unanswered = scan_unanswered_docs(root)
+    if unanswered:
+        total_q = sum(n for _, n in unanswered)
+        print("entropy-machines: %d unanswered question(s) across %d doc(s) in %s/:"
+              % (total_q, len(unanswered), docs_dir_for(root)))
+        for path, n in unanswered:
+            print("  %s -- %d unanswered" % (os.path.relpath(path, root), n))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/bin/tracker

@@ -0,0 +1,153 @@
+#!/bin/sh
+# Adapter dispatcher for the issue tracker. Every caller in this harness goes
+# through this file instead of a backend directly — see
+# docs/TRACKER-ADAPTER.md for the six-command contract every backend
+# implements, and docs/CONFIG.md for config.json.
+#
+#   bin/tracker show i-foo
+#   bin/tracker notes --issue i-foo
+#   bin/tracker remember --issue i-foo "..."
+#   bin/tracker claim i-foo
+#   bin/tracker ready
+#   bin/tracker set i-foo status=done
+#   bin/tracker render
+#
+# `render` is the ONE word this file answers itself. It is not a seventh
+# adapter operation and never reaches a backend: it writes TRACKER.html, a
+# read-only browsable view of the store, into docs.dir (lib/tracker-view.py).
+# Rendering is a view over what a backend already holds, so requiring it of
+# every future backend would be asking each one to ship an HTML generator.
+#
+# `tracker.backend` in config.json picks the implementation: "file" runs the
+# built-in lib/tracker-file over a flat JSON file, "command" shells out to an
+# external tracker binary. This file reads that config once and never again —
+# a backend never re-reads config.json itself (docs/CONFIG.md rule 3).
+#
+# WHY THE WHOLE DISPATCH RUNS IN A SUBSHELL — this is not ergonomics, it is a
+# correctness guard inherited unchanged from the tool this one replaced. That
+# tool's entire job was to `cd` into a hardcoded nested tracker directory
+# before running its backend, because the backend resolved its storage
+# relative to the process's cwd. A caller whose shell keeps its working
+# directory between commands — an agent harness with a persistent shell is
+# exactly this shape — had that `cd` leak into every later command in the
+# same session, silently, and a worktree or a dispatch created after the leak
+# was rooted in the wrong repository. It happened three times before the fix,
+# twice in one day, taking out two dispatched agents at once.
+#
+# This file no longer needs to `cd` anywhere itself — the file backend takes
+# its storage path as configuration, not as an ambient cwd — but the guard is
+# kept anyway and generalized: a `command` backend is arbitrary external code,
+# and nothing stops it from changing directory or leaving other state behind.
+# Everything below runs inside `( ... )`, so nothing the resolved backend does
+# to the working directory survives past this script returning. Do not let
+# the final backend invocation become a bare top-level `exec`; that removes
+# the one property this file exists to guarantee.
+set -e
+
+usage() {
+  cat >&2 <<'EOF'
+usage: bin/tracker show <id>
+       bin/tracker notes [--issue <id>]
+       bin/tracker remember --issue <id> <text>
+       bin/tracker claim <id>
+       bin/tracker ready
+       bin/tracker set <id> <key>=<value> [<key>=<value> ...]
+       bin/tracker render
+EOF
+  exit 2
+}
+
+[ $# -ge 1 ] || usage
+
+. "$(dirname "$0")/../lib/roots.sh"
+ENTROPY_MACHINES_HOME=$(entropy_machines_home "$0")
+entropy_machines_require_root tracker
+
+config="$ENTROPY_MACHINES_HOME/config.json"
+
+# One read of config.json, here, once. Prints four tab-separated fields:
+#   backend            "file" or "command" (defaults to "file")
+#   file backend path  tracker.file.path, defaulted
+#   command bin        tracker.command.bin
+#   command args       tracker.command.args, space-joined (an argument that
+#                       itself contains a space is not representable this
+#                       way — the same limitation any space-joined shell
+#                       config carries; a backend needing one should read its
+#                       own richer config, not rely on this passthrough)
+info=$(python3 - "$config" <<'PY'
+import json, sys
+with open(sys.argv[1], encoding="utf-8") as f:
+    cfg = json.load(f)
+t = cfg.get("tracker") or {}
+backend = t.get("backend") or "file"
+file_path = ((t.get("file") or {}).get("path")) or ".entropy/issues.json"
+command = t.get("command") or {}
+cmd_bin = command.get("bin") or ""
+cmd_args = " ".join(command.get("args") or [])
+# Fields 5 and 6 are for `render` only. They are read HERE, in the one place
+# this harness reads config.json per command (docs/CONFIG.md rule 3), rather
+# than in lib/tracker-view.py — which must stay as ignorant of the config file
+# as a backend is.
+docs_dir = ((cfg.get("docs") or {}).get("dir")) or "entropy-machines-docs"
+project_name = ((cfg.get("project") or {}).get("name")) or ""
+print("\t".join([backend, file_path, cmd_bin, cmd_args, docs_dir, project_name]))
+PY
+) || {
+  echo "tracker: REFUSED — could not read tracker config out of $config." >&2
+  exit 2
+}
+
+backend=$(printf '%s' "$info" | cut -f1)
+file_path=$(printf '%s' "$info" | cut -f2)
+cmd_bin=$(printf '%s' "$info" | cut -f3)
+cmd_args=$(printf '%s' "$info" | cut -f4)
+docs_dir=$(printf '%s' "$info" | cut -f5)
+project_name=$(printf '%s' "$info" | cut -f6)
+
+# RENDER IS INTERCEPTED HERE, before the backend dispatch, so no backend is
+# ever handed a word the six-command contract does not contain. It still runs
+# inside the same subshell guard everything else here does.
+if [ "$1" = "render" ]; then
+  shift
+  view="$ENTROPY_MACHINES_HOME/lib/tracker-view.py"
+  if [ ! -f "$view" ]; then
+    echo "tracker: REFUSED — bin/tracker render needs $view, which is missing." >&2
+    exit 2
+  fi
+  (
+    cd "$ENTROPY_MACHINES_ROOT" &&
+    ENTROPY_MACHINES_TRACKER_PATH="$file_path" \
+    ENTROPY_MACHINES_TRACKER_BACKEND="$backend" \
+    ENTROPY_MACHINES_DOCS_DIR="$docs_dir" \
+    ENTROPY_MACHINES_PROJECT_NAME="$project_name" \
+    exec python3 "$view" "$@"
+  )
+  exit $?
+fi
+
+case "$backend" in
+  file)
+    impl="$ENTROPY_MACHINES_HOME/lib/tracker-file"
+    if [ ! -x "$impl" ]; then
+      echo "tracker: REFUSED — tracker.backend is \"file\" but $impl is missing" >&2
+      echo "  or not executable." >&2
+      exit 2
+    fi
+    # ENTROPY_MACHINES_ROOT is already exported by entropy_machines_require_root; lib/tracker-file
+    # reads it as the root its storage path is relative to.
+    ( cd "$ENTROPY_MACHINES_ROOT" && ENTROPY_MACHINES_TRACKER_PATH="$file_path" exec "$impl" "$@" )
+    ;;
+  command)
+    if [ -z "$cmd_bin" ]; then
+      echo "tracker: REFUSED — tracker.backend is \"command\" but tracker.command.bin" >&2
+      echo "  is empty in $config." >&2
+      exit 2
+    fi
+    ( cd "$ENTROPY_MACHINES_ROOT" && exec "$cmd_bin" $cmd_args "$@" )
+    ;;
+  *)
+    echo "tracker: REFUSED — unknown tracker.backend \"$backend\" in $config" >&2
+    echo "  (want \"file\" or \"command\")." >&2
+    exit 2
+    ;;
+esac

package/docs/AGENT-QUICKSTART.md

@@ -0,0 +1,86 @@
+# Agent quickstart
+
+This doc is for the coding agent bootstrapping and running the harness.
+If you are the project owner (a human), start at [../README.md](../README.md).
+The *why*: [../doctrine/](../doctrine/).
+
+Four roles move one issue through a fixed cycle — dispatch, work, verify, fold —
+enforced by shell gates, not convention. Decisions happen in served HTML docs with
+response boxes, not in chat. Plain tracked files, one git root; prefix the commands
+below if they sit in a subdirectory.
+
+## Step 0 — no `config.json` yet
+
+Your first job and the whole job. Don't stop for permission between steps.
+
+1. **Point `CLAUDE.md` and/or `AGENTS.md` at it** — both if both exist, rewriting
+   nothing already there:
+
+   ```markdown
+   ## entropy-machines
+   Vendored at `<path>`. **Owner** decides and ticks. **Worker** does one scoped
+   issue in an isolated worktree and commits nothing. **Verifier** sweeps a sprint
+   once, on a clean tree. **Orchestrator** dispatches, folds, lands — the only
+   committer. `<path>/bin/status` = live state, `bin/tracker ready` = find work,
+   `bin/dispatch` = the gate before any writing agent, `bin/handoff` = the only way
+   work lands. Doctrine: `<path>/doctrine/`.
+   ```
+
+2. **`bin/init`** — writes `config.json`, gitignores `.entropy-machines/`, copies the
+   orientation PRD into `docs.dir`. A second run exits 2; that refusal is working.
+
+3. **Baseline discovery — record only what you RAN.** `init` writes `suites: []`
+   rather than guess. **Run** the candidate test/typecheck/build commands and enter
+   only those that passed; one that fails is a finding, not an entry. Then fill the
+   PRD's "What we found in your repo" page, saying what you couldn't verify. Leave
+   the open questions — the owner's.
+
+4. **Start `bin/serve`** — actually start it, backgrounded; it holds the terminal.
+   Binds `127.0.0.1` and prints its URL. Run `bin/doclint` first.
+
+Hand over that URL and **stop**. A PRD you answered yourself produces issues nobody
+agreed to.
+
+## The commands
+
+```
+bin/status                                        # read-only: ready, in flight, unanswered
+bin/tracker show|notes|remember|claim|ready|set   # six operations, no more
+bin/dispatch <id> --files "…" --brief "…"         # the gate; paste its block verbatim
+bin/handoff <id> --from <worktree> --verified "<what YOU ran>"
+bin/serve [port] · bin/doclint [path…]
+```
+
+`tracker ready` is the state of the world, not a doc's account of it: it excludes
+held (`heldWhy`) and gated (`gate`), neither a status value — `status` holds only
+`notstarted`/`progress`/`done`. `set` auto-vivifies; there is no `add`.
+`dispatch --files` is advisory; what's enforced is the denylist of files other
+agents hold, pasted into your brief. `handoff --from` lifts the worker's four
+lines; `--verified` never is. See [CONFIG.md](CONFIG.md), [SERVE.md](SERVE.md),
+[TRACKER-ADAPTER.md](TRACKER-ADAPTER.md).
+
+## Never
+
+Commit, unless you are the orchestrator landing via `handoff`. Claim a command you
+did not run. Write a file another live dispatch holds — stop, ship nothing, name it
+in `HANDOFF.md`'s `found:`. Touch another worktree, or run the full build (it
+rewrites committed bookkeeping — use `suites`). Relay another agent's verification.
+Land held work.
+
+## Limits
+
+- **`handoff` cannot read `dispatch`'s notes** (JSONL vs. the older free-text
+  form), so `--lift` copies a held file instead of refusing, interrogation is never
+  required, and a recorded handoff never releases the claim. Read dispatch's
+  overlap warning yourself.
+- **`--lift` exits 1 on `.scratch`** — delete that symlink from the worktree, rerun.
+- **Claude-native in practice.** The gates are POSIX shell; automatic parallel
+  workers in isolated worktrees is a Claude Code capability. Another runner gets
+  the same gates one issue at a time, using `agents/isolated-worker.md` by hand.
+- **Isolation can silently not happen.** `isolation: worktree` branches the repo the
+  *calling session's cwd* is in, so driving one project from a shell in another
+  hands every worker the wrong repo — or one shared checkout where agents see each
+  other's edits. Workers check `git rev-parse --git-common-dir` (never
+  `--show-toplevel`); orchestrators verify cwd, keep scopes disjoint and never `git
+  add -A` while a lane is live. No gate covers it —
+  [../doctrine/WORKFLOW.md](../doctrine/WORKFLOW.md).

package/docs/CONFIG.md

@@ -0,0 +1,68 @@
+# config.json — the project contract
+
+Everything the harness would otherwise hardcode about its host project, at the
+repo root. Nothing in `bin/` or `lib/` may name a language, package manager or
+directory not read from here. It is also the root marker.
+
+`bin/init` writes the first one. It files **no issues** (a PRD is what creates
+issues) and guesses at no command it hasn't run — a fabricated suite makes the
+harness report a broken command as a broken project.
+
+```json
+{
+  "project":    { "name": "my-project", "protectedPaths": [] },
+  "tracker":    { "backend": "file", "file": { "path": ".entropy-machines/issues.json" } },
+  "docs":       { "dir": "entropy-machines-docs", "theme": "high-contrast" },
+  "suites":     [ { "name": "unit", "cmd": ["npm", "test"] },
+                  { "name": "e2e",  "cmd": ["npm", "run", "e2e"], "tag": "slow" } ],
+  "generate":   { "cmd": ["npm", "run", "gen"], "outputs": [] },
+  "changelog":  { "enabled": true, "fragmentDir": "changelog.d",
+                  "collatedFile": "docs/CHANGELOG.md",
+                  "marker": "<!-- BEGIN COLLATED changelog.d -->" },
+  "guards":     { "testPathPatterns": ["tests/**"], "nonCodePatterns": ["**/*.md"],
+                  "buildFailureMarkers": [] },
+  "worktree":   { "linkPaths": ["node_modules"] },
+  "unattended": { "enabled": false, "scheduler": "launchd",
+                  "agent": { "cmd": ["claude", "-p"] } }
+}
+```
+
+Every key is optional — deep-merged over `lib/config.py`'s `DEFAULTS`.
+
+| Key | What it means |
+|---|---|
+| `project.protectedPaths` | Off-limits to a dispatched agent without an override. |
+| `tracker.backend` | `file`, or `command` for your own tracker — [TRACKER-ADAPTER.md](TRACKER-ADAPTER.md). |
+| `docs.dir` / `.theme` | What `bin/serve` serves; `theme` names a file in `lib/themes/`. |
+| `suites` | What "the suites" means. `post-fold-audit` and the verifier run these; `tag` is skippable. |
+| `generate` | `handoff` runs it and fails the fold if anything moves. |
+| `changelog` | Whether a fragment is required per commit. Defaults on. |
+| `guards` | How fail-first classifies a revert, and tells a build failure from a test failure. |
+| `worktree.linkPaths` | Symlinked into every worktree. Without `node_modules` a runtime resolves out of a SIBLING worktree and the agent verifies someone else's code. |
+| `unattended` | The drain loop. `scheduler` is `launchd` (macOS) or `systemd` (a `systemctl --user` timer); omit the key and `bin/drain install` detects one, refusing if neither is present. `on/off/status/now/at` work anywhere. |
+
+## Themes and root
+
+`docs.theme` resolves to `lib/themes/<name>.css` — `high-contrast` (default,
+dark-first) or `daylight` (light-first). A theme is a `:root` token block and
+nothing else, so layout stays in the templates; every theme must define the same
+names with a real value in the bare `:root`, since one defined only under
+`[data-theme=…]` renders unstyled by default.
+`tests/cases/themes-ship-and-apply.sh` catches that by diffing the name sets.
+How `bin/serve` inlines it: [SERVE.md](SERVE.md).
+
+The harness is vendored as **plain tracked files**, never a git repository of
+its own — a nested `.git` shadows the enclosing repo, so commands operate on the
+wrong one; `git clone` and `git submodule` are refused by name. **Root** is
+always the MAIN CHECKOUT, via `--git-common-dir`, never `--show-toplevel`: they
+differ inside a linked worktree, and `.entropy-machines/` lives in the main checkout.
+`lib/roots.sh` is canonical; `lib/config.py` and `lib/config.mjs` mirror it.
+
+## Rules for contributors
+
+1. A new hardcoded path, command or noun in `bin/` or `lib/` is a bug — add a key.
+2. Every key has a working default, or the harness refuses naming the missing
+   key. Silent fallback is what made the original un-portable.
+3. Read once per process and passed down; never re-read from library code.
+4. Anything resolving root independently uses `--git-common-dir` and cites
+   `lib/roots.sh`. Three implementations already drifted apart once.

package/docs/NPM.md

@@ -0,0 +1,91 @@
+# The npm package
+
+`npx entropy-machines init` is a **delivery mechanism, not a runtime**. It
+copies the harness into your repository as plain tracked files and runs
+`bin/init`. After that npm is gone: nothing vendored imports from
+`node_modules`, nothing shells out to `node`, and the harness runs on git, a
+POSIX shell and Python 3. Deleting `node_modules/` changes nothing.
+
+The other route is identical in outcome and needs no Node at all — clone this
+repo and copy `bin/`, `lib/`, `docs/`, `doctrine/`, `hooks/` and `agents/`
+into your project.
+
+## Usage
+
+```sh
+npx entropy-machines init            # -> entropy-machines/ at the repo root
+npx entropy-machines init --dir .    # -> vendored at the repo root instead
+npx entropy-machines --help
+npx entropy-machines --version
+```
+
+`init` copies the six directories plus `LICENSE`, then runs the vendored
+`bin/init` with the repository root as its working directory. To undo it,
+delete the directory. There is no uninstall command, no install receipt and
+no version check, on purpose.
+
+## Why a subdirectory by default
+
+`entropy-machines/` is the default because vendoring at the repo root merges
+the harness's `bin/`, `lib/` and `docs/` into whatever the project already
+has under those names, and those are three of the most commonly taken
+directory names there are. A subdirectory has none of that: it is one
+directory to add, one to `rm -rf`, and `git log` on it shows only harness
+changes. `lib/roots.sh` derives `ENTROPY_MACHINES_HOME` from each script's own `$0`,
+so both layouts work; `docs/AGENT-QUICKSTART.md` already tells the agent to prefix
+every `bin/…` command with the vendored path.
+
+This is **not** the old nested clone. There is no `.git` in the vendored
+directory, so `git` from anywhere inside your project still answers with your
+project — one root, as `lib/roots.sh` requires. `entropy_machines_refuse_nested_clone`
+refuses the layout that does have one.
+
+Use `--dir .` if you want the root layout the README describes, and every
+`bin/…` command in the docs verbatim.
+
+## What it refuses, before writing anything
+
+| Situation | Why |
+|---|---|
+| Not inside a git repository | Vendored files have to be tracked by something. |
+| The destination already holds any of the six directories | An older harness may have edited doctrine in it; your own `bin/` is not ours to merge into. Pass `--dir <path>`. |
+| The destination is inside the package's own directory, or a checkout of this package is inside the destination | It would copy itself over itself, and in a `npm link`ed checkout that tree is where a real `.git` lives. An *installed* copy at `<repo>/node_modules/entropy-machines` is exempt — that is what `npm i -D entropy-machines` plus `--dir .` looks like, and the two trees never overlap. |
+| The destination is outside the repository | Vendoring means committed alongside your code. |
+
+A `.git` directory is never copied, at any depth — filtered by path segment,
+not by trusting the tarball to lack one. A nested `.git` shadows the parent
+repo for every git query and silently misroutes every command in the harness;
+it is the single failure the vendored layout exists to prevent. `__pycache__`,
+`node_modules` and `.DS_Store` are dropped the same way.
+
+## Publishing
+
+`package.json` has no dependencies and no build step.
+
+```sh
+npm pack --dry-run      # the exact file list that will ship
+npm publish
+```
+
+`files` is a whitelist of the six directories, with `!**/__pycache__` and
+`!**/*.pyc` negations — a `.npmignore` does **not** filter inside a
+whitelisted directory, so the negations are what keeps compiled Python out.
+`planning/`, `.entropy-machines/`, `tests/`, `example/`, `entropy-machines-docs/` and
+`CONTRIBUTING.md` are excluded by not being listed; npm excludes `.git`
+unconditionally. `LICENSE`, `README.md` and `package.json` are always
+included — they ship even though `files` does not name them, so the shipped
+list is the six directories plus those three.
+
+Verified against a real `npm pack` on 2026-08-30: the tarball's file list is
+exactly the six directories' tracked contents plus those three, with every
+executable bit intact (20 of the vendored files land as `100755`).
+`bin/entropy-machines-init` is the one packaged file NOT vendored, because it
+is the npm wrapper rather than part of the harness.
+
+`npm pack` reads the WORKING TREE, not HEAD. An uncommitted or untracked file
+inside one of the six directories ships. Pack from a clean tree, and read the
+`npm notice` file list before publishing rather than trusting `files`.
+
+The package version is the npm artifact's version. It is not a harness
+version and nothing checks it — there is no staleness detection anywhere in
+this project.