Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
22 changes: 22 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <dir> [--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 <verb>`. 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.
Expand Down
16 changes: 14 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,21 @@ running an LLM on a schedule. It's off by default; see
## Quickstart

```bash
git clone <this-repo> 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** —
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.31.1
0.31.2
16 changes: 7 additions & 9 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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" }
Expand Down
59 changes: 59 additions & 0 deletions setup.py
Original file line number Diff line number Diff line change
@@ -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})
Empty file added tended/__init__.py
Empty file.
68 changes: 68 additions & 0 deletions tended/cli.py
Original file line number Diff line number Diff line change
@@ -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 <dir>")
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())
54 changes: 54 additions & 0 deletions tests/test_kernel_mechanisms.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
20 changes: 20 additions & 0 deletions tools/brain.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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",
Expand Down
Loading