← BodhiKitCONTENT HISTORY

Update to BodhiKit

Snapshot Nov 11, 2026 · 12:39 UTC · version 1.27.0

WHAT CHANGED

Package or technical metadata updated

Package or technical metadata updated

Observed in package metadata. These changes alone do not establish a new customer-facing feature.

Save BodhiKit and check future changes in Following.

Up to 3 plugins free · no card required.

All fields and original values.

These are saved file metadata. Open a changed file to read its text edits.

Package file

Before

Nov 7, 2026 · 00:09 UTC

a819057813ee23c0e1c57614b41041e1b9cb91a412f3b9486983c09bd2023480

After

Nov 11, 2026 · 12:39 UTC

f50ac611cb5bfb308a3cc89af1d65c56684edd3768e7c6b3e8617b459d038a2d

Package file

Before

Nov 7, 2026 · 00:09 UTC

202a49b10cbf7d48407460d27c19c320fd40550ac24bea0daecc18aab19ff0bc

After

Nov 11, 2026 · 12:39 UTC

5d3f2513de3af57162c242962df0c6a70b4aa5683868e558dcb352c513f9444e

Package file

Before

Nov 7, 2026 · 00:09 UTC

12193

After

Nov 11, 2026 · 12:39 UTC

12188

Package file

Before

Nov 7, 2026 · 00:09 UTC

7548e204b9649b95ce3592cf6598ab8ea68fb6cb01ac6b865ae877bc5754200a

After

Nov 11, 2026 · 12:39 UTC

2543e196897c6119920006a3f54bc443d286d9152ec6e6aee6170c4e0eed141b

Compare saved observations

Download comparison JSON

scripts/bodhi-state

− removed · + added

--- before
+++ after
@@ -20,13 +20,16 @@
 """
 
 import argparse
+import contextlib
 import datetime
+import io
 import json
 import os
 import re
 import shutil
 import sys
 import tempfile
+import urllib.parse
 
 try:
     import fcntl  # POSIX only; locking degrades gracefully elsewhere
@@ -2214,7 +2217,7 @@
     return None
 
 
-def cmd_syllabus(args):
+def build_syllabus(project):
     """Plan order × review evidence × state position, one read-only call.
     Every module the plan declares, in order, with its status (declared
     `skipped`/`done`, else `done`/`current`/`upcoming` from the position the
@@ -2224,13 +2227,13 @@
     no concept was tracked under (not reached yet, or a spelling the review
     file does not use); `unplanned` carries the rows of tracked modules the
     plan does not declare, so no evidence disappears from a dashboard."""
-    state = state_if_present(args.project, {})
-    _, data = load_spaced_review(args.project, create=True)
+    state = state_if_present(project, {})
+    _, data = load_spaced_review(project, create=True)
     t = today()
     concepts = data.get("concepts", [])
     warnings = []
 
-    phases, plan = read_plan_modules(args.project)
+    phases, plan = read_plan_modules(project)
     if phases is None:
         warnings.append("no .bodhi/plan/ directory — a pre-1.7.0 monolithic "
                         "plan.md is not read; /housekeep migrate converts it")
@@ -2246,7 +2249,9 @@
         raw = c.get("module", "(none)")
         entry = tracked.setdefault(norm_module_name(raw),
                                    {"module": raw, "aliases": [], "row": new_module_row(),
-                                    "nextDue": None, "dueToday": 0, "parked": 0})
+                                    "nextDue": None, "dueToday": 0, "parked": 0,
+                                    "items": []})
+        entry["items"].append(c)
         if raw != entry["module"] and raw not in entry["aliases"]:
             entry["aliases"].append(raw)
         tally_module(entry["row"], c, t)
@@ -2284,10 +2289,11 @@
     cur_idx, pos_warnings = plan_position(state, plan)
     warnings.extend(pos_warnings)
 
-    modules, matched_keys = [], set()
+    modules, matched_keys, entries = [], set(), []
     for i, m in enumerate(plan):
         key = norm_module_name(m["name"])
         entry = tracked.get(key) or tracked.get(m["id"])
+        entries.append(entry)
         if entry is not None:
             matched_keys.add(norm_module_name(entry["module"]))
         if m["declaredStatus"]:
@@ -2313,12 +2319,13 @@
         modules.append(row)
 
     untracked = [m["name"] for m in modules if not m["evidence"]["tracked"]]
+    loose = [e for k, e in tracked.items() if k not in matched_keys]
     unplanned = [{"module": e["module"], **{k: v for k, v in evidence(e).items()
                                             if k not in ("tracked", "trackedAs")},
                   "evidenceKind": kind_of_module(e["module"])}
-                 for k, e in tracked.items() if k not in matched_keys]
+                 for e in loose]
 
-    emit({
+    payload = {
         "project": state.get("projectName"),
         "evidenceKind": _KINDS["project"],
         "plan": phases is not None and bool(plan),
@@ -2334,7 +2341,165 @@
         "untracked": untracked,
         "unplanned": unplanned,
         "warnings": warnings,
-    })
+    }
+    return payload, {"today": t, "state": state, "entries": entries, "loose": loose,
+                     "concepts": concepts}
+
+
+# The words /progress uses for a module row (skills/progress/references/
+# module-row.md), held here so `syllabus --markdown` prints them byte for
+# byte (learning-vault/REQ-13, REQ-17). dev/eval t_syllabus_md_words_match_
+# module_row fails when this copy and module-row.md differ.
+SYLLABUS_KIND_WORDS = {
+    "code": ("you write code, and we run it", "code you run"),
+    "problems": ("you work problems, checked against answers I save before you start",
+                 "problems, checked against saved answers"),
+    "writing": ("you write short pieces applying an idea to a new case, read against "
+                "criteria I save first", "writing, read against saved criteria"),
+    "performed": ("you practise away from the screen and tell me how it went, and it "
+                  "counts as your account", "practice, by your account"),
+}
+SYLLABUS_STATUS_WORDS = {"done": "Done", "current": "◀ Current", "upcoming": "Upcoming",
+                         "skipped": "Skipped", "unplanned": "Not in plan"}
+SYLLABUS_UPCOMING_AIM = "Upcoming — aims at: "
+SYLLABUS_TIER_WORDS = {"mastered": ("Solid", "can find where it breaks and explain the "
+                                              "trade-offs"),
+                       "familiar": ("Working", "can use it with guidance"),
+                       "introduced": ("Introduced", "can explain it")}
+SYLLABUS_DUE_CHECK = ", due for a check"
+SYLLABUS_PHRASES = ("How your work is checked: ", "by your account", "not yet observed",
+                    "built with", "due today", "parked")
+
+
+def _syllabus_position(ev):
+    """A module's evidence block in module-row words."""
+    if not ev.get("tracked") or ev.get("summaryTier") is None:
+        return "—"
+    tiers, words = ev["tiers"], SYLLABUS_TIER_WORDS
+    mastered, total, by_report = ev["mastered"], ev["concepts"], ev["masteredByReport"]
+    word, clause = words[ev["summaryTier"]]
+    extra = []
+    if ev["summaryTier"] == "mastered":
+        if mastered == total and ev["dueForCheck"] > 0:
+            word += SYLLABUS_DUE_CHECK
+        if by_report and by_report == mastered:
+            word += ", by your account"
+        elif by_report:
+            word += f"** ({by_report} by your account)**"
+        if mastered < total:
+            extra.append(f"{mastered} solid; {total - mastered} not yet observed")
+    occupied = [(k, tiers.get(k, 0)) for k in ("mastered", "familiar", "introduced")
+                if tiers.get(k, 0)]
+    if len(occupied) > 1:
+        extra.append(", ".join(f"{n} {words[k][0].lower()}" for k, n in occupied))
+    if ev["applied"] < ev["classified"]:
+        extra.append(f"built with {ev['applied']} of {ev['classified']}")
+    out = f"**{word}** — {clause}".replace("**** ", "** ")
+    return out + (f" ({'; '.join(extra)})" if extra else "")
+
+
+def _syllabus_next(ev):
+    if not ev.get("nextDue"):
+        out = "—"
+    else:
+        out = ev["nextDue"] + (f" ({ev['dueToday']} due today)" if ev.get("dueToday") else "")
+    if ev.get("parked"):
+        out += f" · {ev['parked']} parked"
+    return out
+
+
+def render_syllabus_md(project, payload, ctx):
+    """The text of Syllabus.md (learning-vault/REQ-13..REQ-19): the plan in
+    order with where the learner stands and when reviews are due, in the
+    words /progress uses. Depends only on the tracking files and today."""
+    t = ctx["today"]
+    name = payload.get("project") or os.path.basename(os.path.abspath(project))
+    solid_basis = solid_by_report(ctx["concepts"])[1]
+    lines = [f"# Syllabus — {name}", "",
+             "BodhiKit rewrites this file at each session from your learning record, so "
+             "anything written here is replaced. Keep your own notes in `notes/`.", ""]
+    pos = payload.get("position")
+    where = (f"You are on module {pos['index']} of {pos['of']}: {pos['module']}. "
+             if pos else "")
+    lines += [f"{where}Updated {iso(t)}.", ""]
+    kinds = {payload["evidenceKind"], *(m["evidenceKind"] for m in payload["modules"]),
+             *(u["evidenceKind"] for u in payload["unplanned"])}
+    if kinds != {"code"}:
+        lines += ["How your work is checked: "
+                  + SYLLABUS_KIND_WORDS[payload["evidenceKind"]][0], ""]
+
+    # Which plan module each tracked concept sits under, for the due list.
+    shown_module = {}
+    for row, entry in zip(payload["modules"], ctx["entries"]):
+        for c in (entry or {}).get("items", []):
+            shown_module[id(c)] = row["name"]
+    for entry in ctx["loose"]:
+        for c in entry["items"]:
+            shown_module[id(c)] = entry["module"]
+
+    horizon = t + datetime.timedelta(days=7)
+    due = []
+    for c in ctx["concepts"]:
+        nr = parse_date(c.get("nextReview"))
+        if c.get("parked") is True or nr is None or nr > horizon:
+            continue
+        due.append((nr, c.get("name", ""), shown_module.get(id(c), c.get("module", ""))))
+    due.sort(key=lambda d: (d[0], d[1].lower()))
+    lines += ["## Due in the next seven days", ""]
+    lines += [f"- {'due now' if nr <= t else iso(nr)} — {n} ({mod})" for nr, n, mod in due] \
+        or ["Nothing due this week."]
+    lines.append("")
+
+    def concept_lines(items):
+        out = []
+        for c in sorted(items, key=lambda c: str(c.get("name", "")).lower()):
+            outcome = bloom_render(c.get("bloomLevel", 0))["bloomOutcome"]
+            label = ""
+            if concept_tier(c) == "mastered":
+                label = "Solid, by your account — " if solid_basis.get(c.get("name")) \
+                    == "reported" else "Solid — "
+            if c.get("parked") is True:
+                tail = "Parked."
+            elif parse_date(c.get("nextReview")):
+                tail = f"Next review {c['nextReview'][:10]}."
+            else:
+                tail = "No review scheduled."
+            out.append(f"  - {c.get('name', '')} — {label}{outcome}. {tail}")
+        return (["- Concepts you have studied:"] + out) if out else []
+
+    def section(heading, kind, status, ev, planned, terms, items):
+        short = f" ({SYLLABUS_KIND_WORDS[kind][1]})" if kind != payload["evidenceKind"] else ""
+        out = [f"## {heading}{short}", "", f"- Status: {status}",
+               f"- Where you are: {_syllabus_position(ev)}",
+               f"- Mastered: {ev['mastered']}/{ev['concepts']}"
+               if ev.get("masteryPct") is not None else "- Mastered: —",
+               f"- Next review: {_syllabus_next(ev)}"]
+        if planned:
+            out.append("- Planned concepts: " + ", ".join(planned))
+        if terms:
+            out.append("- Key terms: " + ", ".join(terms))
+        return out + concept_lines(items) + [""]
+
+    for row, entry in zip(payload["modules"], ctx["entries"]):
+        status = SYLLABUS_STATUS_WORDS[row["status"]]
+        if row["status"] == "upcoming" and row.get("targetBloomOutcome"):
+            status = SYLLABUS_UPCOMING_AIM + row["targetBloomOutcome"]
+        lines += section(f"Module {row['id']} — {row['name']}", row["evidenceKind"], status,
+                         row["evidence"], row["plannedConcepts"], row["keyTerms"],
+                         (entry or {}).get("items", []))
+    for u, entry in zip(payload["unplanned"], ctx["loose"]):
+        lines += section(f"Not in plan — {u['module']}", u["evidenceKind"],
+                         SYLLABUS_STATUS_WORDS["unplanned"], {"tracked": True, **u}, [], [],
+                         entry["items"])
+    return "\n".join(lines).rstrip("\n") + "\n"
+
+
+def cmd_syllabus(args):
+    payload, ctx = build_syllabus(args.project)
+    if getattr(args, "markdown", False):
+        sys.stdout.write(render_syllabus_md(args.project, payload, ctx))
+        return
+    emit(payload)
 
 
 def cmd_revision_brief(args):
@@ -3278,18 +3443,417 @@
                 errors.append(f"profile projects list structurally broken "
                               f"({type(e).__name__}: {e})")
 
+        # learning-vault: the notes choice beside the profile
+        np_ = os.path.join(os.path.dirname(pp), NOTES_FILE)
+        if os.path.exists(np_):
+            try:
+                notes = load_json_raw(np_)
+                errors.extend(notes_shape_errors(notes))
+                if isinstance(notes, dict) and notes.get("version") != 1:
+                    warnings.append(f"{NOTES_FILE} version is "
+                                    f"{notes.get('version')!r}, expected 1")
+            except (json.JSONDecodeError, OSError) as e:
+                errors.append(f"{NOTES_FILE} unreadable: {e}")
+
     result = {"ok": not errors, "project": project,
               "errors": errors, "warnings": warnings}
     print(json.dumps(result, indent=2))
     sys.exit(0 if not errors else 1)
 
 
+# --- The learning vault (spec learning-vault, decision 0006) ----------------
+#
+# The learner's notes choice lives in `.bodhi-notes.json` beside
+# `.bodhi-profile.json` (shape: skills/notes-setup/references/notes-file.md).
+# Its absence is the 1.26.1 state: never offered, no choice. Disk stays the
+# record; nothing is ever read back from the vault into a tracking file.
+
+NOTES_FILE = ".bodhi-notes.json"
+NOTES_HOME = "Learn with Bodhi"
+NOTES_CHOICES = ("vault", "files", "off")
+# Apps offered per host kind. `carriedBy` says who writes the copy: `script`
+# (notes-sync, on the learner's disk) or `model` (a chat carrying the files).
+# A `model` entry also names `probeHost`, and is offered only once a probe
+# row in docs/no-computer-probe.md or docs/cowork-probe.md records checks 1
+# to 3 as PASS for its `name` on that host (learning-vault/REQ-29, enforced
+# by dev/eval t_notes_apps_need_a_probe_pass).
+NOTES_APPS = {
+    "local": [{"app": "obsidian", "name": "Obsidian", "location": "folder",
+               "carriedBy": "script"}],
+    "cloud-chat": [],
+}
+
+
+def host_kind():
+    """`cloud-chat` where the cloud sandbox's file exchange exists (the
+    marker bodhi-session-context.py uses), else `local`: a host that keeps
+    the learner's folder."""
+    marker = os.environ.get("BODHI_CLOUD_MARKER", "/mnt/user-data")
+    return "cloud-chat" if os.path.isdir(marker) else "local"
+
+
+def apps_offered():
+    return [dict(a) for a in NOTES_APPS.get(host_kind(), [])]
+
+
+def notes_defaults():
+    return {"version": 1, "choice": None, "app": None, "location": None,
+            "agreedOn": None, "offerMadeOn": None, "announced": []}
+
+
+def notes_path(project):
+    pp = find_profile(project)
+    return os.path.join(os.path.dirname(pp), NOTES_FILE) if pp else None
+
+
+def notes_shape_errors(data):
+    """Every way a notes file can be one the readers cannot act on."""
+    if not isinstance(data, dict):
+        return [f"{NOTES_FILE} top level is {type(data).__name__}, expected object"]
+    errs = []
+    choice = data.get("choice")
+    if choice is not None and choice not in NOTES_CHOICES:
+        errs.append(f"{NOTES_FILE} choice {choice!r} is not one of "
+                    f"{', '.join(NOTES_CHOICES)} or null")
+    for key in ("app", "location"):
+        if data.get(key) is not None and not isinstance(data.get(key), str):
+            errs.append(f"{NOTES_FILE} {key} is {type(data.get(key)).__name__}, "
+                        f"expected string or null")
+    if choice == "vault" and not (isinstance(data.get("app"), str)
+                                  and isinstance(data.get("location"), str)
+                                  and data.get("location")):
+        errs.append(f"{NOTES_FILE} choice is vault but app or location is missing")
+    for key in ("agreedOn", "offerMadeOn"):
+        if data.get(key) is not None and parse_date(data.get(key)) is None:
+            errs.append(f"{NOTES_FILE} {key} {data.get(key)!r} is not a date")
+    ann = data.get("announced", [])
+    if not isinstance(ann, list) or not all(isinstance(a, str) for a in ann):
+        errs.append(f"{NOTES_FILE} announced is not a list of course names")
+    return errs
+
+
+def load_notes(project):
+    """(path, data). path is None when no profile is found; data is the
+    file merged over the defaults, unknown fields kept."""
+    path = notes_path(project)
+    data = notes_defaults()
+    if path and os.path.exists(path):
+        raw = load_json(path)
+        errs = notes_shape_errors(raw)
+        if errs:
+            die("; ".join(errs) + " — run `bodhi-state verify`; repair through "
+                "`bodhi-state notes-set`")
+        data.update(raw)
+    return path, data
+
+
+def vault_refusal(location, profile_dir):
+    """Why a vault folder cannot be used (learning-vault/REQ-37), or None."""
+    if not os.path.isdir(location):
+        return (f"the folder {location!r} does not exist — create the vault in the "
+                f"notes app first, then name its folder")
+    loc, home = os.path.realpath(location), os.path.realpath(profile_dir)
+    if loc == home or loc.startswith(home + os.sep):
+        return (f"the folder {location!r} is inside the learning folder {profile_dir!r}; "
+                f"a vault there would copy the files into themselves")
+    if home.startswith(loc + os.sep):
+        return (f"the folder {location!r} holds the learning folder {profile_dir!r}, so "
+                f"the notes app already shows those files — choose files only instead")
+    return None
+
+
+def write_bytes_if_changed(path, data):
+    """Atomic write of `data` only when the file does not already hold it
+    (learning-vault/REQ-24). Returns True when it wrote."""
+    try:
+        with open(path, "rb") as f:
+            if f.read() == data:
+                return False
+    except OSError:
+        pass
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(os.path.abspath(path)),
+                               prefix=".bodhi-", suffix=".tmp")
+    try:
+        try:
+            mode = os.stat(path).st_mode & 0o777
+        except OSError:
+            umask = os.umask(0)
+            os.umask(umask)
+            mode = 0o666 & ~umask
+        try:
+            os.chmod(tmp, mode)
+        except OSError:
+            pass
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+    return True
+
+
+def within(path, top):
+    """True when `path`, symlinks resolved, is `top` or lies under it."""
+    p, t = os.path.realpath(path), os.path.realpath(top)
+    return p == t or p.startswith(t + os.sep)
+
+
+def render_course_md(course):
+    """(Syllabus.md text, None), or (None, why) for a course whose files
+    cannot be read: one broken course never stops the others."""
+    buf = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(buf):
+            install_kinds(course)
+            payload, ctx = build_syllabus(course)
+            return render_syllabus_md(course, payload, ctx), None
+    except SystemExit:
+        try:
+            why = json.loads(buf.getvalue().strip().splitlines()[0]).get("error")
+        except (ValueError, IndexError, AttributeError):
+            why = None
+        return None, why or "its tracking files could not be read"
+
+
+def profile_courses(notes_file):
+    """Every course in the learner's projects list, active or completed,
+    whose folder holds `.bodhi/` (learning-vault/REQ-23)."""
+    top = os.path.dirname(notes_file)
+    lp = os.path.join(top, ".bodhi-profile.projects.json")
+    try:
+        with open(lp, encoding="utf-8") as f:
+            lists = json.load(f)
+    except (OSError, ValueError):
+        return []
+    out = []
+    for key in ("activeProjects", "completedProjects"):
+        for e in lists.get(key, []) if isinstance(lists, dict) else []:
+            name = e.get("name") if isinstance(e, dict) else None
+            if not isinstance(name, str) or not name or os.sep in name or name in (".", ".."):
+                continue
+            course = os.path.join(top, name)
+            if os.path.isdir(os.path.join(course, ".bodhi")) and course not in out:
+                out.append(course)
+    return out
+
+
+def sync_notes(notes, courses):
+    """learning-vault/REQ-12, REQ-20..REQ-24: write each course's Syllabus.md
+    and, for a vault, copy it, its revision sheets and Courses.md into the
+    home. Nothing is read back. Failures are collected, never raised."""
+    res = {"written": [], "unchanged": [], "failed": [], "firstArrival": []}
+    choice = notes.get("choice")
+    if choice not in ("vault", "files"):
+        return res
+    t = iso(today())
+
+    def put(path, data):
+        try:
+            (res["written"] if write_bytes_if_changed(path, data)
+             else res["unchanged"]).append(path)
+            return True
+        except OSError as e:
+            res["failed"].append({"path": path, "why": e.strerror or str(e)})
+            return False
+
+    home = None
+    if choice == "vault":
+        loc = notes.get("location") or ""
+        home = os.path.join(loc, NOTES_HOME)
+        if not os.path.isdir(loc):
+            res["failed"].append({"path": loc, "why": "the vault folder is not there"})
+            home = None
+        else:
+            try:
+                os.makedirs(home, exist_ok=True)
+            except OSError as e:
+                res["failed"].append({"path": home, "why": e.strerror or str(e)})
+                home = None
+            if home and not within(home, loc):
+                res["failed"].append({"path": home, "why": "it leads outside the vault"})
+                home = None
+
+    for course in courses:
+        name = os.path.basename(os.path.abspath(course))
+        text, why = render_course_md(course)
+        if text is None:
+            res["failed"].append({"path": course, "why": why})
+            continue
+        data = text.encode("utf-8")
+        put(os.path.join(course, "Syllabus.md"), data)
+        if home is None:
+            continue
+        cdir = os.path.join(home, name)
+        if os.path.lexists(cdir) and not within(cdir, home):
+            res["failed"].append({"path": cdir, "why": "it leads outside the Learn with "
+                                                       "Bodhi folder, so nothing was copied"})
+            continue
+        try:
+            os.makedirs(os.path.join(cdir, "revision"), exist_ok=True)
+        except OSError as e:
+            res["failed"].append({"path": cdir, "why": e.strerror or str(e)})
+            continue
+        if not within(os.path.join(cdir, "revision"), home):
+            res["failed"].append({"path": cdir, "why": "its revision folder leads outside "
+                                                       "the Learn with Bodhi folder"})
+            continue
+        if put(os.path.join(cdir, "Syllabus.md"), data) and \
+                name not in notes.get("announced", []):
+            res["firstArrival"].append(name)
+        src = os.path.join(course, "revision")
+        try:
+            sheets = sorted(f for f in os.listdir(src) if f.endswith(".md"))
+        except OSError:
+            sheets = []
+        for f in sheets:
+            dst = os.path.join(cdir, "revision", f)
+            if os.path.exists(dst) and not f.startswith(t):
+                continue  # an earlier day's sheet, once copied, is never touched again
+            try:
+                with open(os.path.join(src, f), "rb") as fh:
+                    put(dst, fh.read())
+            except OSError as e:
+                res["failed"].append({"path": dst, "why": e.strerror or str(e)})
+
+    if home is not None:
+        try:
+            names = sorted(d for d in os.listdir(home)
+                           if not d.startswith(".")
+                           and os.path.isfile(os.path.join(home, d, "Syllabus.md")))
+        except OSError:
+            names = []
+        index = ["# Learn with Bodhi", "",
+                 "BodhiKit rewrites this page at each session. Each course's syllabus is "
+                 "linked below; its revision sheets sit beside it in `revision/`.", ""]
+        index += [f"- [{n}]({urllib.parse.quote(n)}/Syllabus.md)" for n in names]
+        put(os.path.join(home, "Courses.md"), ("\n".join(index) + "\n").encode("utf-8"))
+    return res
+
+
+def record_announced(path, notes, names):
+    if names:
+        notes["announced"] = list(notes.get("announced", [])) + \
+            [n for n in names if n not in notes.get("announced", [])]
+        write_json(path, notes)
+
+
+def cmd_notes_sync(args):
+    """learning-vault: the session-close writes. The Stop hook runs it for
+    each course the session closed; `--all` covers every course in the
+    profile. Exits 0 whatever failed: the failures are in `failed`."""
+    path, notes = load_notes(args.project)
+    if path is None:
+        emit({"choice": None, "written": [], "unchanged": [], "failed": [],
+              "firstArrival": [], "reason": "no profile"})
+        return
+    if notes.get("choice") in ("vault", "files"):
+        # Locks only when there is work: with no choice this command must
+        # leave no file behind, a lock file included (learning-vault/REQ-7).
+        bdir = os.path.join(args.project, ".bodhi")
+        if os.path.isdir(bdir):
+            acquire_lock(bdir)
+        acquire_lock(os.path.dirname(path))
+    courses = profile_courses(path) if args.all else [os.path.abspath(args.project)]
+    res = sync_notes(notes, courses)
+    record_announced(path, notes, res["firstArrival"])
+    emit({"choice": notes.get("choice"), **res})
+
+
+def cmd_notes_show(args):
+    """learning-vault: what the notes setup reads first (read-only)."""
+    path = notes_path(args.project)
+    data = notes_defaults()
+    if path and os.path.exists(path):
+        _, data = load_notes(args.project)
+    loc = data.get("location")
+    emit({"profileFound": path is not None,
+          "notesFile": path,
+          "exists": bool(path and os.path.exists(path)),
+          "choice": data.get("choice"), "app": data.get("app"),
+          "location": loc,
+          "home": os.path.join(loc, NOTES_HOME) if loc else None,
+          "agreedOn": data.get("agreedOn"), "offerMadeOn": data.get("offerMadeOn"),
+          "host": host_kind(), "appsOffered": apps_offered()})
+
+
+def cmd_notes_set(args):
+    """learning-vault/REQ-4, REQ-6, REQ-37: record the learner's agreed
+    notes choice. The skill calls this only after the learner agreed."""
+    path, data = load_notes(args.project)
+    if path is None:
+        die("no .bodhi-profile.json found walking up from the project — the notes "
+            "setting lives beside it, so it cannot be recorded for a course outside "
+            "the learning folder")
+    choice = args.choice
+    if choice == "vault":
+        offered = {a["app"]: a for a in apps_offered()}
+        if not args.app:
+            die("--choice vault needs --app (one of: "
+                f"{', '.join(offered) or 'none on this host'})")
+        if args.app not in offered:
+            die(f"the app {args.app!r} is not offered on this host "
+                f"({host_kind()}); offered: {', '.join(offered) or 'none'}")
+        if not args.location:
+            die("--choice vault needs --location <the vault's folder>")
+        location = os.path.abspath(os.path.expanduser(args.location))
+        why = vault_refusal(location, os.path.dirname(path))
+        if why:
+            die(why)
+        home = os.path.join(location, NOTES_HOME)
+        probe = os.path.join(home, ".bodhikit-write-test")
+        try:
+            os.makedirs(home, exist_ok=True)
+            with open(probe, "w", encoding="utf-8") as f:
+                f.write("BodhiKit checks it can write here; this file is removed at once.\n")
+            os.unlink(probe)
+        except OSError as e:
+            die(f"cannot write in {home!r} ({e.strerror or e}) — check the folder's "
+                f"permissions; nothing was recorded")
+        data.update({"choice": "vault", "app": args.app, "location": location,
+                     "agreedOn": iso(today())})
+    elif choice == "files":
+        data.update({"choice": "files", "agreedOn": iso(today())})
+    else:
+        data["choice"] = "off"
+    write_json(path, data)
+    # learning-vault/REQ-23: a choice that writes starts with every course.
+    res = sync_notes(data, profile_courses(path))
+    record_announced(path, data, res["firstArrival"])
+    loc = data.get("location")
+    emit({"choice": data["choice"], "app": data.get("app"), "location": loc,
+          "home": os.path.join(loc, NOTES_HOME) if loc and data["choice"] == "vault" else None,
+          "agreedOn": data.get("agreedOn"), "notesFile": path, "sync": res})
+
+
+def cmd_notes_offered(args):
+    """learning-vault/REQ-10: record that the one-time offer was made. Never
+    fails for a missing profile: the Stop hook calls it."""
+    path, data = load_notes(args.project)
+    if path is None:
+        emit({"recorded": False, "reason": "no profile to record it beside"})
+        return
+    already = data.get("offerMadeOn") is not None
+    if not already:
+        data["offerMadeOn"] = iso(today())
+        write_json(path, data)
+    emit({"recorded": True, "already": already, "offerMadeOn": data["offerMadeOn"]})
+
+
 # --- CLI --------------------------------------------------------------------
 
 READ_ONLY_COMMANDS = {cmd_due, cmd_mastery, cmd_calibration, cmd_retention,
                       cmd_export_anonymized, cmd_session_brief, cmd_snapshot,
                       cmd_gate_check, cmd_verify, cmd_revision_brief,
-                      cmd_syllabus}
+                      cmd_syllabus, cmd_notes_show}
+# Takes its own locks once it knows it will write (learning-vault/REQ-7).
+LOCKS_ITSELF = {cmd_notes_sync}
+# Learner-wide: --project may be the learning folder itself, which holds the
+# profile but no .bodhi/ (learning-vault, /notes-setup).
+LEARNER_WIDE = {cmd_notes_show, cmd_notes_set, cmd_notes_offered, cmd_notes_sync}
 
 def main():
     p = argparse.ArgumentParser(prog="bodhi-state", description=__doc__,
@@ -3492,6 +4056,8 @@
 
     s = sub.add_parser("syllabus",
                        help="plan order × review evidence × position: every plan module in order with status and module evidence (read-only)")
+    s.add_argument("--markdown", action="store_true",
+                   help="print the text of the course's Syllabus.md instead of JSON (learning vault)")
     s.set_defaults(fn=cmd_syllabus)
 
     s = sub.add_parser("revision-brief",
@@ -3512,18 +4078,39 @@
     s = sub.add_parser("verify", help="schema sanity check (lint + Stop hook)")
     s.set_defaults(fn=cmd_verify)
 
+    s = sub.add_parser("notes-show",
+                       help="the learner's notes choice and the apps offered on this host (read-only)")
+    s.set_defaults(fn=cmd_notes_show)
+
+    s = sub.add_parser("notes-set", help="record the learner's agreed notes choice")
+    s.add_argument("--choice", required=True, choices=NOTES_CHOICES)
+    s.add_argument("--app", help="with --choice vault: an app from notes-show appsOffered")
+    s.add_argument("--location", help="with --choice vault: the vault's folder")
+    s.set_defaults(fn=cmd_notes_set)
+
+    s = sub.add_parser("notes-offered", help="record that the one-time notes offer was made")
+    s.set_defaults(fn=cmd_notes_offered)
+
+    s = sub.add_parser("notes-sync",
+                       help="write Syllabus.md and copy the notes into the vault (session close)")
+    s.add_argument("--all", action="store_true",
+                   help="every course in the learner's profile, not just --project")
+    s.set_defaults(fn=cmd_notes_sync)
+
     args = p.parse_args()
     # One exclusive lock per project for the whole read-mutate-write run —
     # closes the two-terminal lost-update race (1.11.1). Profile writes lock
     # the profile's directory too.
     shared = args.fn in READ_ONLY_COMMANDS
     bdir = os.path.join(args.project, ".bodhi")
-    if os.path.isdir(bdir):
-        acquire_lock(bdir, shared=shared)
     profile = find_profile(args.project)
-    if profile:
-        acquire_lock(os.path.dirname(profile), shared=shared)
-    install_kinds(args.project)
+    if args.fn not in LOCKS_ITSELF:
+        if os.path.isdir(bdir):
+            acquire_lock(bdir, shared=shared)
+        if profile:
+            acquire_lock(os.path.dirname(profile), shared=shared)
+    if not (args.fn in LEARNER_WIDE and not os.path.isdir(bdir)):
+        install_kinds(args.project)
     args.fn(args)
 
 
Full technical diff · 9 changed fields

changed /files/.codex-plugin~1plugin.json/sha256

BEFORE
"a819057813ee23c0e1c57614b41041e1b9cb91a412f3b9486983c09bd2023480"
AFTER
"f50ac611cb5bfb308a3cc89af1d65c56684edd3768e7c6b3e8617b459d038a2d"

changed /files/references~1knowledge~1evidence-kinds.md/sha256

BEFORE
"202a49b10cbf7d48407460d27c19c320fd40550ac24bea0daecc18aab19ff0bc"
AFTER
"5d3f2513de3af57162c242962df0c6a70b4aa5683868e558dcb352c513f9444e"

changed /files/references~1knowledge~1evidence-kinds.md/size

BEFORE
12193
AFTER
12188

changed /files/references~1openai-runtime.md/sha256

BEFORE
"7548e204b9649b95ce3592cf6598ab8ea68fb6cb01ac6b865ae877bc5754200a"
AFTER
"2543e196897c6119920006a3f54bc443d286d9152ec6e6aee6170c4e0eed141b"

changed /files/references~1openai-runtime.md/size

BEFORE
5791
AFTER
7033

changed /files/scripts~1bodhi-state/sha256

BEFORE
"ab622afe7a327e1ff4d743102456cdb502be4d228714f31753ada4bd71abf5c7"
AFTER
"ca82590a10c3ef0cc629d3a208676cf8b033d17b9665847d1e0c9a37955de050"

changed /files/scripts~1bodhi-state/size

BEFORE
163667
AFTER
190177

added /files/skills~1notes-setup~1SKILL.md

BEFORE
Field was absent
AFTER
{
  "sha256": "3f477dbaf4a76ad0fa33617f5e6370e3e5cd6f3f4363ae6969d1c3b2f8c71420",
  "size": 6894
}

added /files/skills~1notes-setup~1references~1notes-file.md

BEFORE
Field was absent
AFTER
{
  "sha256": "8440f58a14f115a7450f63bc4150cb6ca1d894b8d8e7e58b16493efa962ab351",
  "size": 2115
}
Full snapshot data
{
  "files": {
    ".codex-plugin/plugin.json": {
      "sha256": "f50ac611cb5bfb308a3cc89af1d65c56684edd3768e7c6b3e8617b459d038a2d",
      "size": 1908
    },
    "assets/bodhikit-icon.png": {
      "sha256": "86a71e096653ce6d87bca9c9dde2e433d1e4f85969b12295c06693cbfa7e43f6",
      "size": 707205
    },
    "references/knowledge/ai-learning-safeguards.md": {
      "sha256": "46a09877f8c0fa3446445fbb2295a06da3e900625bb91731b6cf81148e33f057",
      "size": 1301
    },
    "references/knowledge/assessment-framework.md": {
      "sha256": "94236e74f3b6986d118e8ed18c3a9c205f8ae7b04259c11ebdca22d52a7a6cb6",
      "size": 8740
    },
    "references/knowledge/blooms-taxonomy.md": {
      "sha256": "0b454bdeff7d48a2f46d215ddb1a03d1f7839db1f827240261acce18fcfdf6e0",
      "size": 10995
    },
    "references/knowledge/constructivism.md": {
      "sha256": "f68b61167d15eff336edc64eb4bacc2ac0b8c38928e671c31870c7fc278e6dbe",
      "size": 1399
    },
    "references/knowledge/deliberate-practice.md": {
      "sha256": "624b614001793674918ee2a143c8eb6678d9f59b05d1427a043838b439b3cfbc",
      "size": 1418
    },
    "references/knowledge/difficulty-calibration.md": {
      "sha256": "80309abfcff9f59de2ad0158d5eecf6c89a2ef928379a97055c5ab2a0059f625",
      "size": 10162
    },
    "references/knowledge/evidence-kinds.md": {
      "sha256": "5d3f2513de3af57162c242962df0c6a70b4aa5683868e558dcb352c513f9444e",
      "size": 12188
    },
    "references/knowledge/feynman-technique.md": {
      "sha256": "64632b01075efbcb798d99a463080f209394a3fe6ce2eb468d0e504302bbc2b5",
      "size": 11890
    },
    "references/knowledge/growth-mindset.md": {
      "sha256": "c81ca91e7ff8308e6ed13bbe1448a160733c5fa67b88103348c320f7fe284b7c",
      "size": 1288
    },
    "references/knowledge/mentoring-theory.md": {
      "sha256": "30600120e7c5f7deefc0d0b8d3d59de32e25d0661402bfb693d6569dd2a0d030",
      "size": 1278
    },
    "references/knowledge/metacognition.md": {
      "sha256": "d7f5e8644584475b420b9c502331d2d30dd5a457fa176892e58e481535e55370",
      "size": 2669
    },
    "references/knowledge/pair-programming.md": {
      "sha256": "b3d7dc3fd7383205d93528223240718001f962b4fb138c79104984bf19060b5c",
      "size": 1382
    },
    "references/knowledge/scientific-debugging.md": {
      "sha256": "b92ad48403876021820918eee418e533223aa4af90560f991decf4e2349c74db",
      "size": 2008
    },
    "references/knowledge/spaced-repetition.md": {
      "sha256": "00c5f6616079b17ac3ed3cb44ad05496aa16539f1cf6587a91975b9053988ee8",
      "size": 7644
    },
    "references/knowledge/state-lifecycle.md": {
      "sha256": "443bdfe1fecc2c680532ccc038e40c2ff92aeeca84899a513ceacae26081346a",
      "size": 4440
    },
    "references/knowledge/state-migration.md": {
      "sha256": "6da9a09846019003bd785a6bb9e7447cb0b610676536c07431209c06f429477a",
      "size": 10368
    },
    "references/knowledge/state-ops.md": {
      "sha256": "8f6b0e63f4fedc7bb6814d1a7faa024aad6e9341fbfa383928d18f5091037a00",
      "size": 18650
    },
    "references/knowledge/state-schema.md": {
      "sha256": "033613b1e873217f17d8800f5b0f449e589e1aa958aded7257b6748dd4dc7b6e",
      "size": 18487
    },
    "references/knowledge/teaching-personality.md": {
      "sha256": "01a29e4ef1185a15488fde8f1f3e3a7454b4f8dfcff64fd0adb3189e2fdc7c35",
      "size": 8823
    },
    "references/openai-runtime.md": {
      "sha256": "2543e196897c6119920006a3f54bc443d286d9152ec6e6aee6170c4e0eed141b",
      "size": 7033
    },
    "references/roles/code-reviewer.md": {
      "sha256": "d897ff4689f4b65511470c60e8799ae06996ce789de3250c88dc2461936e210b",
      "size": 4364
    },
    "references/roles/resource-finder.md": {
      "sha256": "926bfc0af602b20b5676aec91bb49e2d4545d99fc6be08f5ea137147aeaffcaf",
      "size": 3391
    },
    "references/roles/skill-assessor.md": {
      "sha256": "9255b876bc292a56f3bdf7f26a7a60933717f1f524339b80bb0e4413f0128856",
      "size": 5044
    },
    "references/roles/trajectory-analyzer.md": {
      "sha256": "9adf09de763028ed87b968776e2ab5bd599263c81b8c50b9c354ad73cad67a52",
      "size": 9555
    },
    "rules/learning-project.md": {
      "sha256": "750e4231e54a74092eb318de07df7f01aa9eca5fec5d8859a00fbb7b5edfea18",
      "size": 2990
    },
    "scripts/bodhi-state": {
      "sha256": "ca82590a10c3ef0cc629d3a208676cf8b033d17b9665847d1e0c9a37955de050",
      "size": 190177
    },
    "skills/assess/SKILL.md": {
      "sha256": "39dba44d9b53dc968b029806fc96fcf9e6e4eab9b64c444508e5e15e6ee97dda",
      "size": 5238
    },
    "skills/continue/SKILL.md": {
      "sha256": "53c556696123c7dbfeaf27bd901737798fddce6fce6a0c3b830b32acbfb604fd",
      "size": 13946
    },
    "skills/debug-together/SKILL.md": {
      "sha256": "6e62ded8a7f189ec78f8a21750cfad31ca7229f0d1968169faf869d0bb6de6a8",
      "size": 9725
    },
    "skills/evaluate/SKILL.md": {
      "sha256": "164c2e003501727cf05bc3c237ec7e4d9efc0b6cde6c6d238ccd0e1f373a6176",
      "size": 15607
    },
    "skills/forget/SKILL.md": {
      "sha256": "fc11af3254b6d65d5ef30140bee116cffe26f6d544ef0ee64a72a88d2406c46d",
      "size": 5946
    },
    "skills/housekeep/SKILL.md": {
      "sha256": "d63e45fecf3006b919884f7166dc102cf3423e805b4c681ef45830ae58063431",
      "size": 16089
    },
    "skills/learn/SKILL.md": {
      "sha256": "024120add5310120e8de56e525539e62d2ebcd4fb1467847b47996873fd1d299",
      "size": 18650
    },
    "skills/learn/references/host-without-files.md": {
      "sha256": "16638a6b467f2a50e10f5efd021c90fbde9041bc9c9fb0bc8917af2f22103167",
      "size": 3212
    },
    "skills/mentor/SKILL.md": {
      "sha256": "ef99a69b02abd8f33fc10c211622fbd9e385726debffd4f4c6d21af8db420605",
      "size": 8784
    },
    "skills/notes-setup/SKILL.md": {
      "sha256": "3f477dbaf4a76ad0fa33617f5e6370e3e5cd6f3f4363ae6969d1c3b2f8c71420",
      "size": 6894
    },
    "skills/notes-setup/references/notes-file.md": {
      "sha256": "8440f58a14f115a7450f63bc4150cb6ca1d894b8d8e7e58b16493efa962ab351",
      "size": 2115
    },
    "skills/pair/SKILL.md": {
      "sha256": "8812ed3d05efc19f4a92f7a315e00602051905d77df364089b3ed87bb92d53e7",
      "size": 14249
    },
    "skills/plan/SKILL.md": {
      "sha256": "394343a9b57f70888689903bf1c2fb31f8cd7fe2b251c894b2d5d225324dbde8",
      "size": 9495
    },
    "skills/practice/SKILL.md": {
      "sha256": "5ac7a97f86f7b8e331f80163854ea09f64995fce5fbc85ad8b61097a35db70fc",
      "size": 15981
    },
    "skills/progress/SKILL.md": {
      "sha256": "d56fb4517b5ec518215562fa58971308c3c80de9c7f3b3aed749154c84a52d79",
      "size": 15871
    },
    "skills/progress/references/module-row.md": {
      "sha256": "5a700cb3681db017a58e99f17f820989b52e04059c9f678350a9b1d97f28e74b",
      "size": 4497
    },
    "skills/quiz/SKILL.md": {
      "sha256": "75f91a1a25be25eac18b601c2630b26ec05d27e50e55111acef5e231f1a8c7a9",
      "size": 13222
    },
    "skills/reflect/SKILL.md": {
      "sha256": "0f9fe2b497677d900c03bb45ea772dc49b7b2e5315153b09d7de2c28771a3547",
      "size": 13690
    },
    "skills/reflect/references/revision-sheet.md": {
      "sha256": "40b9a5a76f36d33fb5a9c45283a51715958938e12c6561df62b6ad7e9e915db8",
      "size": 4299
    },
    "skills/resources/SKILL.md": {
      "sha256": "3550f8bbaa6920bbfb0fb0957d8a51d1a30fce034cf163c63352b32b5d62de79",
      "size": 5773
    },
    "skills/review/SKILL.md": {
      "sha256": "f2130a6ce3514ea078cf863e5e028fe32277cfe8be7d2ff0288d499cad7c9ea6",
      "size": 5731
    },
    "skills/teach-back/SKILL.md": {
      "sha256": "efb0015bb54fb98ac157ea08de91454d25b4d02fee8b95c24be02dc7f4b2d45f",
      "size": 18553
    },
    "skills/teach/SKILL.md": {
      "sha256": "1f185fce529561e6102dea26d35874e91121830d9ff7851cd45d92a4716262d4",
      "size": 18586
    },
    "skills/teach/references/prerequisite-gate.md": {
      "sha256": "0c9213e3a711c6df19c1631b1ce608aa31539d6f76e81835590abbec1ffa2ce5",
      "size": 4591
    },
    "skills/teach/references/understanding-only.md": {
      "sha256": "2a883c79768339e0ce991f5663ec7df8aa991ec9d801309c47e96ff948b07b3e",
      "size": 2861
    }
  }
}

SHA-256 of public snapshot: a147beb3cbef282baf92d2c107b51fc388930425b9ef9d7506672fc5d7031a6d