diff --git a/.gitignore b/.gitignore
index fd9f40d..6ce60c3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,5 +18,6 @@ __pycache__/
 *.log
 
 # omo runtime state written into the project .omo dir
+.omo/
 thread-tools/
 senpi-task/
diff --git a/README.md b/README.md
index 7af30bc..0dba70e 100644
--- a/README.md
+++ b/README.md
@@ -6,12 +6,12 @@
 
 My AI learning system from this video: [How I Use AI to Learn Things](https://www.youtube.com/watch?v=kzcI5F4tGiU).
 
-This is a personal system I built for myself, shared as-is. Originally built as a pi configuration; this fork is an omo configuration: the teaching philosophy encoded in a skill, a few small extensions, and subagent briefs.
+This is a personal system I built for myself, shared as-is. Originally built as a pi configuration; this fork is an omo configuration: the teaching philosophy encoded in a skill, a few small extensions, and task briefs.
 
 ## What's in it
 
-- `skills/teach/` — the philosophy and the process; `researcher.md` is the brief for the researcher subagent
-- `skills/visualize/` — adds a correct, minimal diagram to a lesson when an idea is clearer as a picture; `mermaid-maker.md` and `svg-maker.md` are the briefs for the maker subagents
+- `skills/teach/` — the philosophy and the process; `researcher.md` is the brief for the researcher task
+- `skills/visualize/` — adds a correct, minimal diagram to a lesson when an idea is clearer as a picture; `mermaid-maker.md` and `svg-maker.md` are the maker briefs (dispatched through omo's `task` tool)
 - `extensions/ask-user-question.ts` — the agent asks you questions through a UI popup
 - `extensions/quiz.ts` — graded questions with instant feedback (✓/✗, correct answer, explanation)
 - `extensions/md-log.ts` — link a markdown file to the session (`/md-log <file>`, `/md-unlog`)
@@ -28,6 +28,14 @@ git submodule add <this repo> .pi
 
 Then open omo in that directory and trust the project when asked (project skills and extensions only load in trusted projects).
 
+## Vault setup (Obsidian)
+
+The lesson log and visuals live in your vault; everything else stays out of it:
+
+- Keep your learning project root **inside your Obsidian vault** and open omo there. Makers publish PNGs to `<project>/viz/`, which must be in-vault for embeds to resolve.
+- Create the log note **before** linking: `/md-log` links an existing file, it never creates one (`touch lesson.md`, then `/md-log lesson.md`). The note must be in the **same vault** as `viz/` — Obsidian resolves `![[name]]` embeds by filename within one vault only.
+- Nothing to exclude from Sync: `.pi/`, `.omo/`, and `.git` all start with a dot, and Obsidian Sync always excludes hidden files and folders (only `.obsidian` is the exception). Lesson notes and `viz/*.png` images sync as normal vault content.
+
 ## Requirements
 
 - [omo](https://omo.dev). Subagents run through its built-in `task` tool, which spawns a worker that reads the brief file and follows it.