diff --git a/.gitignore b/.gitignore
index 53003a9..20bec76 100644
--- a/.gitignore
+++ b/.gitignore
@@ -82,3 +82,7 @@ mcp-arch.yaml
# uv writes this as a side effect of `uv pip install`; the manifests
# (requirements*.txt) are the declared dependency surface.
uv.lock
+
+# Packaging output
+build/
+*.egg-info/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf08a81..0e1c0be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,28 @@ All notable changes to the brain kernel. Versions correspond to
shipped roadmap slices (`wiki/brain/roadmap.md` holds the full
narrative; the ADR shelf holds the decisions).
+## 0.31.2, 2026-10-25
+Published on PyPI as `tended`, so `uvx tended init my-wiki` creates a
+working instance anywhere.
+- The wheel carries the kernel manifest (every path in
+ `KERNEL_COPY_PATHS`, plus `sources/README.md` and `brain.config.yml`)
+ under `tended/kernel/` in the package, copied at build time by `setup.py`. The
+ top-level `tools` package is no longer shipped, so it cannot collide in
+ site-packages. Checkout use is unchanged.
+- New `tended` command: `tended init
[--org X]` births a full
+ instance from the bundled kernel, `tended --version` prints the version,
+ and any other verb says to run it inside an instance with
+ `python3 tools/brain.py `. The `brain` console script is gone;
+ `tools/brain` and `python3 tools/brain.py` remain.
+- `init --full` now makes every copied file and directory writable by the
+ new owner, so an instance born from a read-only install (a wheel in
+ site-packages) can be edited and its seeded ADR filter can run.
+- `init --full` recreates the UI's `ui/src/content/docs` link to `wiki/`,
+ which a wheel cannot carry, and the source package ships the kernel too
+ so the wheel builds from it.
+- README leads with `uvx tended init my-wiki`; the clone route is the
+ contributor path. Nothing inside an instance is renamed.
+
## 0.31.1, 2026-10-25
Final polish: documentation made to match the code, and defects that
could mislead or hurt a user fixed. No new features.
diff --git a/README.md b/README.md
index 8292cba..fbde222 100644
--- a/README.md
+++ b/README.md
@@ -36,9 +36,21 @@ running an LLM on a schedule. It's off by default; see
## Quickstart
```bash
-git clone brain && cd brain
+uvx tended init my-wiki # or: pipx run tended init my-wiki
+cd my-wiki
python3 tools/brain.py setup # idempotent bootstrap: env, config, hooks, timer, UI
-brain # opens the app
+tools/brain # opens the app
+```
+
+This project was called brain and is now published as `tended`. The
+files inside an instance keep the old name (`tools/brain.py`,
+`brain.config.yml`, the skills), so nothing already born needs to change.
+
+To work on the kernel itself, clone it instead:
+
+```bash
+git clone https://github.com/misabegovic/tended.git && cd tended
+python3 tools/brain.py setup
```
That's the whole surface. The app is the **rendered knowledge** —
diff --git a/VERSION b/VERSION
index f176c94..c415e1c 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.31.1
+0.31.2
diff --git a/pyproject.toml b/pyproject.toml
index 30aacb5..64b0350 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,11 +1,9 @@
-# Packaging for the brain kernel. The repo itself is the artifact —
-# a brain lives as a checkout (or a born instance) because the CLI
-# resolves everything relative to the repository root. This manifest
-# makes `pip install -e .` provide the `brain` console script per
-# checkout (editable installs only, by design), and gives releases
-# canonical metadata.
+# Packaging for tended (formerly the brain kernel). The wheel carries
+# the kernel manifest as data inside the package (copied at build time
+# by setup.py) and a `tended` command that births an instance from it.
+# Inside a checkout or an instance, tools/brain.py is run directly.
[project]
-name = "brain-kernel"
+name = "tended"
description = "An LLM-maintained knowledge substrate: governed markdown wiki, queue-and-tend self-maintenance, connectors, composable SQL views, MCP serving, and a chat-first workbench."
readme = "README.md"
license = "MIT"
@@ -20,10 +18,10 @@ cluster = ["scikit-learn"]
full = ["tiktoken", "datasette", "pytest", "scikit-learn"]
[project.scripts]
-brain = "tools.brain:main"
+tended = "tended.cli:main"
[tool.setuptools]
-packages = ["tools"]
+packages = ["tended"]
[tool.setuptools.dynamic]
version = { file = "VERSION" }
diff --git a/setup.py b/setup.py
new file mode 100644
index 0000000..6ce625e
--- /dev/null
+++ b/setup.py
@@ -0,0 +1,59 @@
+"""Bundles the kernel manifest into the wheel inside the tended package."""
+
+import ast
+import os
+import shutil
+from pathlib import Path
+
+from setuptools import setup
+from setuptools.command.build_py import build_py
+from setuptools.command.egg_info import egg_info
+
+ROOT = Path(__file__).resolve().parent
+EXTRA_PATHS = ["sources/README.md", "brain.config.yml"]
+SKIP_NAMES = ("node_modules", "__pycache__", ".build-cache", "dist",
+ ".pytest_cache")
+SKIP = shutil.ignore_patterns(*SKIP_NAMES, "*.pyc")
+
+
+def manifest() -> list[str]:
+ tree = ast.parse((ROOT / "tools" / "brain.py").read_text())
+ for node in tree.body:
+ if isinstance(node, ast.Assign) and any(
+ getattr(t, "id", "") == "KERNEL_COPY_PATHS"
+ for t in node.targets):
+ return list(ast.literal_eval(node.value))
+ raise SystemExit("KERNEL_COPY_PATHS not found in tools/brain.py")
+
+
+class BuildPy(build_py):
+ def run(self):
+ super().run()
+ dest = Path(self.build_lib) / "tended" / "kernel"
+ for rel in manifest() + EXTRA_PATHS:
+ src, dst = ROOT / rel, dest / rel
+ dst.parent.mkdir(parents=True, exist_ok=True)
+ if src.is_dir():
+ shutil.rmtree(dst, ignore_errors=True)
+ shutil.copytree(src, dst, symlinks=True, ignore=SKIP)
+ else:
+ shutil.copyfile(src, dst)
+
+
+class EggInfo(egg_info):
+ def find_sources(self):
+ super().find_sources()
+ for rel in manifest() + EXTRA_PATHS + ["setup.py"]:
+ src = ROOT / rel
+ if src.is_file():
+ self.filelist.append(rel)
+ continue
+ for dirpath, dirnames, filenames in os.walk(src):
+ dirnames[:] = [d for d in dirnames if d not in SKIP_NAMES]
+ for name in filenames:
+ if not name.endswith(".pyc"):
+ self.filelist.append(
+ str(Path(dirpath, name).relative_to(ROOT)))
+
+
+setup(cmdclass={"build_py": BuildPy, "egg_info": EggInfo})
diff --git a/tended/__init__.py b/tended/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tended/cli.py b/tended/cli.py
new file mode 100644
index 0000000..7cf6a66
--- /dev/null
+++ b/tended/cli.py
@@ -0,0 +1,68 @@
+"""The `tended` command: births an instance from the bundled kernel."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+
+
+def kernel_root() -> Path:
+ bundled = HERE / "kernel"
+ if (bundled / "tools" / "brain.py").exists():
+ return bundled
+ checkout = HERE.parent
+ if (checkout / "tools" / "brain.py").exists():
+ return checkout
+ raise SystemExit("tended: no kernel found next to this package")
+
+
+def version() -> str:
+ return (kernel_root() / "VERSION").read_text().strip()
+
+
+def init(args: argparse.Namespace) -> int:
+ root = kernel_root()
+ cmd = [sys.executable, str(root / "tools" / "brain.py"), "init",
+ args.path, "--full"]
+ if args.org:
+ cmd += ["--org", args.org]
+ if args.force:
+ cmd.append("--force")
+ env = {**os.environ, "BRAIN_DIR": str(root), "PYTHONDONTWRITEBYTECODE": "1"}
+ return subprocess.run(cmd, env=env).returncode
+
+
+def main(argv: list[str] | None = None) -> int:
+ argv = list(sys.argv[1:] if argv is None else argv)
+ parser = argparse.ArgumentParser(
+ prog="tended",
+ description="Birth a tended knowledge base. Everything else runs "
+ "inside the instance with python3 tools/brain.py.")
+ parser.add_argument("--version", action="store_true")
+ sub = parser.add_subparsers(dest="verb")
+ p = sub.add_parser("init", help="create a full instance in ")
+ p.add_argument("path")
+ p.add_argument("--org", default="")
+ p.add_argument("--force", action="store_true")
+ if argv and argv[0] not in ("init", "--version", "-h", "--help"):
+ print(f"tended only creates instances. Run `{argv[0]}` inside an "
+ f"instance with: python3 tools/brain.py {argv[0]}",
+ file=sys.stderr)
+ return 2
+ args = parser.parse_args(argv)
+ if args.version:
+ print(f"tended {version()}")
+ return 0
+ if args.verb == "init":
+ return init(args)
+ parser.print_help()
+ return 2
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/test_kernel_mechanisms.py b/tests/test_kernel_mechanisms.py
index 5b92b2c..1e9bc35 100644
--- a/tests/test_kernel_mechanisms.py
+++ b/tests/test_kernel_mechanisms.py
@@ -290,3 +290,57 @@ def test_internal_refs_scans_ui_source_strings():
"internal-refs missed a dangling path in ui/src source")
finally:
rogue.unlink()
+
+
+# ---------- tended packaging ----------------------------------------------
+
+def test_birth_from_read_only_kernel_is_writable(tmp_path):
+ """A read-only source (an installed wheel) births an owned instance."""
+ import os
+ import shutil
+ import subprocess
+ kernel = tmp_path / "kernel"
+ skip = shutil.ignore_patterns("node_modules", "__pycache__", "*.pyc")
+ for rel in [*brain.KERNEL_COPY_PATHS, "sources/README.md",
+ "brain.config.yml"]:
+ src, dst = REPO / rel, kernel / rel
+ dst.parent.mkdir(parents=True, exist_ok=True)
+ if src.is_dir():
+ shutil.copytree(src, dst, symlinks=True, ignore=skip)
+ else:
+ shutil.copyfile(src, dst)
+ (kernel / "ui" / "src" / "content" / "docs").unlink()
+ for p in [kernel, *kernel.rglob("*")]:
+ if not p.is_symlink():
+ p.chmod(p.stat().st_mode & ~0o222)
+ target = tmp_path / "instance"
+ env = {**os.environ, "BRAIN_DIR": str(kernel)}
+ try:
+ proc = subprocess.run(
+ [sys.executable, str(kernel / "tools" / "brain.py"), "init",
+ str(target), "--full", "--org", "T"],
+ env=env, capture_output=True, text=True, timeout=180)
+ assert proc.returncode == 0, proc.stderr[:800]
+ for p in (target / "tools" / "brain.py",
+ target / "wiki" / "brain" / "adrs",
+ target / "sources" / "README.md"):
+ assert p.stat().st_mode & 0o200, f"not writable: {p}"
+ docs = target / "ui" / "src" / "content" / "docs"
+ assert docs.is_symlink() and docs.resolve() == (target / "wiki").resolve()
+ finally:
+ for p in [kernel, *kernel.rglob("*")]:
+ if not p.is_symlink():
+ p.chmod(p.stat().st_mode | 0o700)
+
+
+def test_tended_command_refuses_other_verbs():
+ import subprocess
+ run = lambda *a: subprocess.run(
+ [sys.executable, "-m", "tended.cli", *a], cwd=REPO,
+ capture_output=True, text=True)
+ version = run("--version")
+ assert version.returncode == 0
+ assert (REPO / "VERSION").read_text().strip() in version.stdout
+ other = run("search", "x")
+ assert other.returncode != 0
+ assert "python3 tools/brain.py search" in other.stderr
diff --git a/tools/brain.py b/tools/brain.py
index 1db722e..e7f1b46 100755
--- a/tools/brain.py
+++ b/tools/brain.py
@@ -9233,6 +9233,16 @@ def cmd_schedule(args) -> int:
]
+def _make_owner_writable(path: Path) -> None:
+ """Copies keep the source's modes; a read-only source (an installed
+ package) would otherwise birth an instance its owner cannot edit."""
+ paths = [path]
+ if path.is_dir() and not path.is_symlink():
+ paths += [p for p in path.rglob("*") if not p.is_symlink()]
+ for p in paths:
+ p.chmod(p.stat().st_mode | 0o200 | (0o100 if p.is_dir() else 0))
+
+
def _init_full(target: Path, org: str) -> int:
"""Birth a working instance: manifest copy + fresh scaffold."""
src_root = REPO
@@ -9253,6 +9263,7 @@ def _init_full(target: Path, org: str) -> int:
"dist", "*.pyc", ".pytest_cache"))
else:
shutil.copy2(src, dst)
+ _make_owner_writable(dst)
# Drop the brain's own initiative children from the seeded ADR trail:
# an ADR carrying parent_epic dangles without its epic (intentionally
@@ -9266,9 +9277,18 @@ def _init_full(target: Path, org: str) -> int:
p.unlink()
(target / "CLAUDE.md").symlink_to("AGENTS.md")
+ # A wheel cannot carry the UI's link to the wiki, so a kernel installed
+ # from one arrives without it (or with the link followed into a copy).
+ docs = target / "ui" / "src" / "content" / "docs"
+ if not docs.is_symlink():
+ if docs.exists():
+ shutil.rmtree(docs)
+ docs.parent.mkdir(parents=True, exist_ok=True)
+ docs.symlink_to(Path("..") / ".." / ".." / "wiki")
(target / "sources").mkdir(exist_ok=True)
shutil.copy2(src_root / "sources" / "README.md",
target / "sources" / "README.md")
+ _make_owner_writable(target / "sources" / "README.md")
(target / "log").mkdir(exist_ok=True)
(target / "log" / "log.md").write_text("")
for d in ("_views", "_archive", "_overlaps", "_state",