fix(setup): wizard install — voice template packaged + relocatable nell launcher

Two bugs surfaced during Hana's wizard validation against the
Phase 7 bundled .app:

1. install_voice_template tried to read docs/voice-drafts/nell-voice.md
   from a path resolved relative to brain/setup.py — which is
   correct in source-installs but FAILS in any wheel install
   (the wheel ships only the brain/ package, not docs/). The
   nell-example voice template threw FileNotFoundError on every
   install_only path including the Phase 7 .app.

2. The pip-generated nell entry point at python-runtime/bin/nell
   had its python interpreter shebang baked to an absolute path
   from the build machine. The .app shipped a script that tried
   to exec /Users/<builder>/.../python-runtime/bin/python3 — a
   path that exists on the build machine and fails everywhere
   else. Hana's traceback shows the source-tree's brain/cli.py
   getting imported instead of the bundled one because the
   shebang resolved to the build host's python.

Fix #1 — package the template:
  * docs/voice-drafts/nell-voice.md moved to
    brain/voice_templates/nell-voice.md
  * brain/voice_templates/__init__.py added so it's a real
    package (hatchling auto-includes everything under
    brain/)
  * install_voice_template reads via importlib.resources
    files('brain.voice_templates').joinpath('nell-voice.md');
    no repo_root parameter, no path resolution
  * verified: wheel ships brain/voice_templates/nell-voice.md;
    nell init --voice-template nell-example writes the file
    correctly from a tmp NELLBRAIN_HOME

Fix #2 — relocatable nell launcher:
  * build_python_runtime.sh post-install step replaces bin/nell
    with a 6-line /bin/sh wrapper that resolves $SCRIPT_DIR via
    cd "$(dirname "$0")" then execs "$SCRIPT_DIR/python3"
    with a -c 'from brain.cli import main; sys.exit(main())'
    payload. Whatever directory the python-runtime tree gets
    copied to, bin/nell finds its own python next door
  * Windows: pip's Scripts/nell.exe is already a relative-path
    launcher binary, so the script keeps it untouched
  * verified: bundled bin/nell runs --version from /tmp,
    init --voice-template nell-example writes voice.md

Test updates:
  * test_install_voice_template_nell_example_copies_packaged_file
    replaces the old fake-repo-root test; asserts the canonical
    nell voice opens with '## 1. Who you are' and is > 1000 bytes
  * test_install_voice_template_nell_example_missing_file_raises
    removed (the importlib.resources path can't fail this way
    once the file ships in the wheel; ValueError on unknown
    template still tested)

1470 → 1469 (one removed test). Ruff clean. macOS arm64 .app
re-bundled at ~/wizard-validation/ with codesign verify pass.

Author: Hana

app/build_python_runtime.sh

@@ -125,12 +125,47 @@ echo "[build] installing brain + deps into bundled python"
 "$PY_BIN" -m pip install --quiet --upgrade pip
 "$PY_BIN" -m pip install --quiet "$WHEEL"
 
-# 5. Verify the brain entry point + import work in the bundled python
+# 5. Replace the pip-generated nell entry point with a relocatable
+# wrapper. pip bakes the absolute path of *this build's* python into
+# the script's shebang, which means the bundled nell.app will try to
+# exec the build host's python-runtime/python3 on a USER'S
+# machine where that path does not exist (or worse, exists from a
+# stale build). The wrapper resolves the bundled python by relative
+# path so the runtime tree is fully relocatable.
+if [ "$HOST_OS" != "windows" ]; then
+  echo "[build] writing relocatable nell wrapper (Unix)"
+  cat > "$NELL_BIN" <<'NELL_WRAPPER'
+#!/bin/sh
+# Relocatable nell launcher — runs whichever python3 lives next door.
+# Generated by app/build_python_runtime.sh; do not pip-reinstall over.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec "$SCRIPT_DIR/python3" -c '
+import sys
+from brain.cli import main
+sys.exit(main())
+' "$@"
+NELL_WRAPPER
+  chmod +x "$NELL_BIN"
+else
+  # On Windows pip generates Scripts/nell.exe, a small launcher binary
+  # that already resolves python via relative path lookup. No wrapper
+  # rewrite needed. (If a future Windows setuptools ever bakes an
+  # absolute path, mirror the Unix wrapper using a .bat file.)
+  echo "[build] Windows: keeping pip-generated Scripts/nell.exe (relative-path launcher)"
+fi
+
+# 6a. Verify the brain entry point + import work in the bundled python
 echo "[build] verify brain import + entry point"
 "$PY_BIN" -c "import brain; import brain.cli; print('  brain:', brain.__file__)"
 "$NELL_BIN" --version
-
-# 6. Strip pyc cache + tests dirs to shrink the bundle a bit
+echo "[build] verify nell can resolve brain.voice_templates"
+"$PY_BIN" -c "
+from importlib.resources import files
+content = files('brain.voice_templates').joinpath('nell-voice.md').read_text(encoding='utf-8')
+print('  nell-voice.md:', len(content), 'bytes')
+"
+
+# 6b. Strip pyc cache + tests dirs to shrink the bundle a bit
 echo "[build] strip __pycache__ + tests from site-packages"
 find "$RUNTIME_DIR" -type d -name "__pycache__" -prune -exec rm -rf {} + 2>/dev/null || true
 find "$SITE_PACKAGES" -type d -name "tests" -prune -exec rm -rf {} + 2>/dev/null || true

brain/setup.py

@@ -49,7 +49,6 @@
     ),
 }
 
-_NELL_VOICE_REPO_PATH = Path("docs/voice-drafts/nell-voice.md")
 _PERSONA_NAME_RE = re.compile(r"^[A-Za-z0-9_-]{1,40}$")
 
 
@@ -102,8 +101,6 @@ def write_persona_config(
 def install_voice_template(
     persona_dir: Path,
     template: str,
-    *,
-    repo_root: Path | None = None,
 ) -> Path | None:
     """Drop a starter voice.md into the persona dir based on `template`.
 
@@ -115,10 +112,12 @@ def install_voice_template(
         template: One of VOICE_TEMPLATES keys ("default" / "skip" leave
             no file; "nell-example" copies the canonical Nell voice.md
             as a starting point — the user is expected to edit it).
-        repo_root: Path to the companion-emergence repo (for locating
-            the example voice.md). Defaults to the parent of this file's
-            grandparent (which is the package root in dev installs).
-            Pass an explicit path in tests.
+
+    The Nell example template is packaged inside the brain wheel at
+    ``brain/voice_templates/nell-voice.md`` and read via
+    :mod:`importlib.resources`, so this works whether the framework
+    is installed from source, from a wheel, or from inside the
+    Phase 7 bundled NellFace.app.
     """
     if template not in VOICE_TEMPLATES:
         raise ValueError(
@@ -133,17 +132,20 @@ def install_voice_template(
         return None
 
     if template == VOICE_TEMPLATE_NELL_EXAMPLE:
-        if repo_root is None:
-            # Default: this module lives at brain/setup.py inside the repo
-            repo_root = Path(__file__).resolve().parent.parent
-        src = repo_root / _NELL_VOICE_REPO_PATH
-        if not src.exists():
-            raise FileNotFoundError(
-                f"Nell voice example not found at {src}. The repo may "
-                f"have been installed without docs/. Author your voice.md "
-                f"by hand or use template='default'."
+        from importlib.resources import files
+
+        try:
+            content = (
+                files("brain.voice_templates")
+                .joinpath("nell-voice.md")
+                .read_text(encoding="utf-8")
             )
-        voice_path.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
+        except (FileNotFoundError, ModuleNotFoundError) as exc:
+            raise FileNotFoundError(
+                "Nell voice example not packaged with this install of brain. "
+                "Reinstall from a recent wheel, or use template='default'."
+            ) from exc
+        voice_path.write_text(content, encoding="utf-8")
         return voice_path
 
     # Defensive — the membership check above should make this unreachable

brain/voice_templates/__init__.py

@@ -89,28 +89,23 @@ def test_install_voice_template_default_writes_no_file(tmp_path: Path) -> None:
         assert not (persona_dir / "voice.md").exists()
 
 
-def test_install_voice_template_nell_example_copies_file(tmp_path: Path) -> None:
-    """nell-example template copies docs/voice-drafts/nell-voice.md verbatim."""
-    # Build a fake repo root with the example file present
-    repo_root = tmp_path / "repo"
-    (repo_root / "docs" / "voice-drafts").mkdir(parents=True)
-    sample = "# fake voice\n\nfor testing\n"
-    (repo_root / "docs" / "voice-drafts" / "nell-voice.md").write_text(sample)
-
+def test_install_voice_template_nell_example_copies_packaged_file(
+    tmp_path: Path,
+) -> None:
+    """nell-example writes the packaged brain/voice_templates/nell-voice.md.
+
+    The template ships inside the brain wheel so it's available whether
+    the framework is installed from source, from a wheel, or from inside
+    the Phase 7 bundled NellFace.app — no `repo_root` lookup needed.
+    """
     persona_dir = tmp_path / "persona"
-    result = install_voice_template(persona_dir, "nell-example", repo_root=repo_root)
+    result = install_voice_template(persona_dir, "nell-example")
     assert result == persona_dir / "voice.md"
-    assert result.read_text() == sample
-
-
-def test_install_voice_template_nell_example_missing_file_raises(tmp_path: Path) -> None:
-    """If the repo doesn't have the example (e.g. installed without docs/),
-    fail loudly — better than writing nothing silently."""
-    repo_root = tmp_path / "empty_repo"
-    repo_root.mkdir()
-    persona_dir = tmp_path / "persona"
-    with pytest.raises(FileNotFoundError, match="not found"):
-        install_voice_template(persona_dir, "nell-example", repo_root=repo_root)
+    content = result.read_text(encoding="utf-8")
+    # The shipped Nell voice draft is the canonical one — opens with
+    # the section-1 header.
+    assert "## 1. Who you are" in content
+    assert len(content) > 1000  # not an empty file
 
 
 def test_install_voice_template_unknown_raises(tmp_path: Path) -> None: