dotbrain 0.4.4__tar.gz → 0.4.6__tar.gz

{dotbrain-0.4.4 → dotbrain-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotbrain
-Version: 0.4.4
+Version: 0.4.6
 Summary: Wires project Brainspaces and skills into coding agents.
 Project-URL: Homepage, https://github.com/arminzou/dotbrain
 Project-URL: Repository, https://github.com/arminzou/dotbrain

{dotbrain-0.4.4 → dotbrain-0.4.6}/README.md

@@ -153,6 +153,10 @@ automatically at session start and are available as slash commands.
   accepted work to private execution items.
 - **`write-agent-docs`** — write public project docs, private Brain material, and user-owned
   skills so agents retrieve and follow them predictably.
+- **`brain-site`** — give a Brain a private site with `dotbrain site`, and keep its sidebar and
+  theme.
+- **`teach-me`** — learn your own project from its Brain over many sessions, with learning records
+  and lessons kept in `.brain/learning/`.
 
 See [docs/skills.md](docs/skills.md) for the full set.
 

{dotbrain-0.4.4 → dotbrain-0.4.6}/docs/cli-reference.md

@@ -32,6 +32,7 @@ Reference for the public `dotbrain` CLI.
 │ agents     Link dotbrain vendor-native subagents into agent runtimes.        │
 │ beads      Manage beads tracker state and backend.                           │
 │ hook       Run dotbrain hook entrypoints.                                    │
+│ site       Set up and run a Brain's private site.                            │
 └──────────────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -277,6 +278,88 @@ Reference for the public `dotbrain` CLI.
 └──────────────────────────────────────────────────────────────────────────────┘
 ```
 
+## `dotbrain site`
+
+```text
+
+ Usage: dotbrain site [OPTIONS] COMMAND [ARGS]...
+
+ Set up and run a Brain's private site.
+
+┌─ Options ────────────────────────────────────────────────────────────────────┐
+│ --help  -h        Show this message and exit.                                │
+└──────────────────────────────────────────────────────────────────────────────┘
+┌─ Commands ───────────────────────────────────────────────────────────────────┐
+│ init     Give a Brain a site: create .brain/site/ with site.yaml, the home   │
+│          page, and the manual.                                               │
+│ dev      Serve the Brain site locally with live reload (127.0.0.1).          │
+│ build    Build the Brain site; fails on a nav link to a missing page.        │
+│ preview  Serve the last build locally (127.0.0.1).                           │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+## `dotbrain site build`
+
+```text
+
+ Usage: dotbrain site build [OPTIONS]
+
+ Build the Brain site; fails on a nav link to a missing page.
+
+┌─ Options ────────────────────────────────────────────────────────────────────┐
+│ --name          TEXT  Brainspace name. Defaults to the current repo's        │
+│                       .brain.                                                │
+│ --help  -h            Show this message and exit.                            │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+## `dotbrain site dev`
+
+```text
+
+ Usage: dotbrain site dev [OPTIONS]
+
+ Serve the Brain site locally with live reload (127.0.0.1).
+
+┌─ Options ────────────────────────────────────────────────────────────────────┐
+│ --name          TEXT  Brainspace name. Defaults to the current repo's        │
+│                       .brain.                                                │
+│ --help  -h            Show this message and exit.                            │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+## `dotbrain site init`
+
+```text
+
+ Usage: dotbrain site init [OPTIONS]
+
+ Give a Brain a site: create .brain/site/ with site.yaml, the home page, and
+ the manual.
+
+┌─ Options ────────────────────────────────────────────────────────────────────┐
+│ --name           TEXT  Brainspace name. Defaults to the current repo's       │
+│                        .brain.                                               │
+│ --title          TEXT  Site title. Defaults to '<name> Brain'.               │
+│ --help   -h            Show this message and exit.                           │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+## `dotbrain site preview`
+
+```text
+
+ Usage: dotbrain site preview [OPTIONS]
+
+ Serve the last build locally (127.0.0.1).
+
+┌─ Options ────────────────────────────────────────────────────────────────────┐
+│ --name          TEXT  Brainspace name. Defaults to the current repo's        │
+│                       .brain.                                                │
+│ --help  -h            Show this message and exit.                            │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
 ## `dotbrain skills`
 
 ```text

{dotbrain-0.4.4 → dotbrain-0.4.6}/docs/skills.md

@@ -50,6 +50,17 @@ Skill linking is operator-managed:
 - **`write-agent-docs`** — writing discipline for public project docs, private Brain material,
   user-owned skills, and guidance agents reach through pointers
 
+## Brain Site
+
+- **`brain-site`** — set up, maintain, and build a Brain's private site with `dotbrain site`: arrange
+  the sidebar, preview, fix a failed build, and write pages with VitePress and Mermaid syntax
+
+## Learning
+
+- **`teach-me`** — teach the operator their project from its Brain over many sessions: explain in
+  conversation, walk a learning path tracked as a `learn:` bead, record what was demonstrated, and
+  capture approved lessons into `.brain/learning/`
+
 ## Installing Them
 
 The skills arrive with the plugin, installed once per agent runtime rather than per repo. See

{dotbrain-0.4.4 → dotbrain-0.4.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dotbrain"
-version = "0.4.4"
+version = "0.4.6"
 description = "Wires project Brainspaces and skills into coding agents."
 requires-python = ">=3.11"
 license = "MIT"

{dotbrain-0.4.4 → dotbrain-0.4.6}/src/dotbrain/__init__.py

@@ -4,4 +4,4 @@ A testable Python CLI for wiring repos into Brainspaces, seeding Brains, and
 managing skills. Exposes the workflow commands plus pure path/contract helpers.
 """
 
-__version__ = "0.4.4"
+__version__ = "0.4.6"

{dotbrain-0.4.4 → dotbrain-0.4.6}/src/dotbrain/brainspaces.py

@@ -45,6 +45,9 @@ def seed_brain(brainspace: Path, dotbrain_home: Path) -> None:
     ``DOTBRAIN.md`` and ``README.md`` files are dotbrain-owned and overwritten
     so package template changes propagate. All other files, including
     ``project.yaml``, are project-owned and are only written when missing.
+    ``site/`` is never seeded: having it opts a Brain into a Brain site, so only
+    ``dotbrain site init`` writes it. In a Brain that has a site, the dotbrain-owned
+    ``site/configure.md`` manual is refreshed like ``DOTBRAIN.md``.
     """
 
     brain = Path(brainspace) / ".brain"
@@ -54,9 +57,12 @@ def seed_brain(brainspace: Path, dotbrain_home: Path) -> None:
         raise FileNotFoundError("package resource templates/brain/AGENTS.md is missing")
 
     for rel, src in resource_loader.iter_resource_files("templates/brain"):
+        site_manual = rel.as_posix() == "site/configure.md"
+        if rel.parts[0] == "site" and not (site_manual and (brain / "site").is_dir()):
+            continue
         dest = brain / rel
         dest.parent.mkdir(parents=True, exist_ok=True)
-        if src.name not in ("DOTBRAIN.md", "README.md") and dest.exists():
+        if src.name not in ("DOTBRAIN.md", "README.md") and not site_manual and dest.exists():
             continue
         content = src.read_text(encoding="utf-8")
         if dest.is_file() and dest.read_bytes() == content.encode("utf-8"):

{dotbrain-0.4.4 → dotbrain-0.4.6}/src/dotbrain/cli.py

@@ -13,7 +13,7 @@ import typer
 
 from dotbrain import __version__
 from dotbrain import doctor as doctor_mod
-from dotbrain import adopter_repos, beads as beads_mod, bootstrap as bootstrap_mod, config, brainspaces, hooks, migrate, paths, resource_loader, skills, subagents, workflows
+from dotbrain import adopter_repos, beads as beads_mod, bootstrap as bootstrap_mod, config, brainspaces, hooks, migrate, paths, resource_loader, site as site_mod, skills, subagents, workflows
 
 app = typer.Typer(
     help="dotbrain CLI for wiring project Brainspaces and skills into coding agents.",
@@ -25,10 +25,12 @@ skills_app = typer.Typer(help="Link dotbrain skills into agent runtimes.", no_ar
 agents_app = typer.Typer(help="Link dotbrain vendor-native subagents into agent runtimes.", no_args_is_help=True)
 beads_app = typer.Typer(help="Manage beads tracker state and backend.", no_args_is_help=True)
 hook_app = typer.Typer(help="Run dotbrain hook entrypoints.", no_args_is_help=True)
+site_app = typer.Typer(help="Set up and run a Brain's private site.", no_args_is_help=True)
 app.add_typer(skills_app, name="skills")
 app.add_typer(agents_app, name="agents")
 app.add_typer(beads_app, name="beads")
 app.add_typer(hook_app, name="hook")
+app.add_typer(site_app, name="site")
 
 
 @app.callback()
@@ -699,3 +701,63 @@ def _render_global_agent_link(root: Path, target: str) -> None:
         typer.echo(f"agent-link: warning: {warning}", err=True)
     for line in result.logs:
         typer.echo(line if line.startswith("global:") else f"  {line}")
+
+
+_SITE_NAME = typer.Option(None, "--name", help="Brainspace name. Defaults to the current repo's .brain.")
+
+
+def _site_brain(name: Optional[str]) -> tuple[Path, Path]:
+    root = paths.resolve_dotbrain_home()
+    try:
+        return root, site_mod.find_brain(root, name)
+    except site_mod.SiteError as exc:
+        typer.echo(f"site: {exc}", err=True)
+        raise typer.Exit(1)
+
+
+@site_app.command("init")
+def site_init(
+    name: Optional[str] = _SITE_NAME,
+    title: Optional[str] = typer.Option(None, "--title", help="Site title. Defaults to '<name> Brain'."),
+) -> None:
+    """Give a Brain a site: create .brain/site/ with site.yaml, the home page, and the manual."""
+    _, brain = _site_brain(name)
+    created = site_mod.init(brain, title)
+    for path in created:
+        typer.echo(f"site: created {path}")
+    if site_mod.site_settings_file(brain) in created:
+        typer.echo(
+            "site: every docs/ page is in the sidebar; trim or regroup it in site.yaml, then run "
+            "`dotbrain site dev`. .brain/site/configure.md, the home page's Configure this site button, explains the settings."
+        )
+    if not created:
+        typer.echo("site: already set up; nothing changed")
+
+
+def _site_run(command: str, name: Optional[str]) -> None:
+    root, brain = _site_brain(name)
+    try:
+        out = site_mod.run_site(command, dotbrain_home=root, brain=brain)
+    except site_mod.SiteError as exc:
+        typer.echo(f"site: {exc}", err=True)
+        raise typer.Exit(1)
+    if command == "build":
+        typer.echo(f"site: built {brain.parent.name} into {out}")
+
+
+@site_app.command("dev")
+def site_dev(name: Optional[str] = _SITE_NAME) -> None:
+    """Serve the Brain site locally with live reload (127.0.0.1)."""
+    _site_run("dev", name)
+
+
+@site_app.command("build")
+def site_build(name: Optional[str] = _SITE_NAME) -> None:
+    """Build the Brain site; fails on a nav link to a missing page."""
+    _site_run("build", name)
+
+
+@site_app.command("preview")
+def site_preview(name: Optional[str] = _SITE_NAME) -> None:
+    """Serve the last build locally (127.0.0.1)."""
+    _site_run("preview", name)

{dotbrain-0.4.4 → dotbrain-0.4.6}/src/dotbrain/doctor.py

@@ -11,7 +11,7 @@ from collections.abc import Callable
 from dataclasses import dataclass, field
 from pathlib import Path
 
-from dotbrain import config, paths, resource_loader
+from dotbrain import config, paths, resource_loader, site
 from dotbrain.adopter_repos import is_dotbrain_repo
 
 # Same shape as bootstrap.Runner; injected so tests can record without real subprocess calls.
@@ -194,6 +194,20 @@ def _check_project_wiring(brainspace: Path, dotbrain_home: Path) -> list[Finding
     return findings
 
 
+# --------------------------------------------------------------------------- Brain site
+
+
+def _check_brain_site(brainspace: Path, *, run: Runner = _default_run) -> list[Finding]:
+    """Node matters only for a Brain with a site; every other Brain skips this check."""
+    if not (brainspace / ".brain" / "site").is_dir():
+        return []
+    try:
+        site.check_node(run)
+    except site.SiteError as exc:
+        return [Finding("warn", f"Brain site: {exc}", f"install Node {site.MIN_NODE_TEXT} or later to run 'dotbrain site'")]
+    return [Finding("ok", "Brain site: Node available")]
+
+
 # --------------------------------------------------------------------------- beads state
 
 
@@ -273,6 +287,8 @@ def run_doctor(
         if shutil.which("bd"):
             findings += _check_beads_state(brainspace, name, root, run=run)
 
+        findings += _check_brain_site(brainspace, run=run)
+
         if findings:
             report.projects[name] = findings