1 files changed, 8 insertions, 3 deletions

diff --git a/doc.txt b/doc.txt
index 42929bf..87b0db4 100644
--- a/doc.txt
+++ b/doc.txt
@@ -1,4 +1,4 @@
-vr — read code and take notes; every call is logged.
+vr — read code and take notes; every call is logged in a private jj sidecar.
 
 read a file (line-numbered, relative to a jj revision):
   vr read FILE                  whole file
@@ -19,5 +19,10 @@ vr query -op note shows both the session-local id and the log-wide id used by
 -reply and vrsite /note/N permalinks.
 
 REV is any jj revset; default @ (the working copy).
-Every command takes -log FILE for where to append the log
-(default ./vr-log.jsonl, or $VR_LOG); use an absolute path across repos.
+The repo-local revset alias vr_log names the log change. vr creates it lazily
+as an anonymous child of root(); it never appears in the project working copy.
+Every new entry records the full target change id and exact target commit id.
+An existing repo-root vr-log.jsonl is read and imported on the first append;
+vr leaves that legacy working-tree file for you to remove after migration.
+The sidecar has no bookmark and is deliberately local-only: a fresh clone will
+not contain it, so include the jj repository in backups when notes matter.