seren-margin 2.1.0__tar.gz → 2.2.0__tar.gz

{seren_margin-2.1.0/seren_margin.egg-info → seren_margin-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seren-margin
-Version: 2.1.0
+Version: 2.2.0
 Summary: Private notes-to-self for an AI assistant. Standalone, opt-in, opinionated.
 Author: Chad Roesler
 License-Expression: AGPL-3.0-or-later

{seren_margin-2.1.0 → seren_margin-2.2.0}/seren_margin/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.1.0'
-__version_tuple__ = version_tuple = (2, 1, 0)
+__version__ = version = '2.2.0'
+__version_tuple__ = version_tuple = (2, 2, 0)
 
-__commit_id__ = commit_id = 'g5b51c6bf2'
+__commit_id__ = commit_id = 'g77bceb68b'

{seren_margin-2.1.0 → seren_margin-2.2.0}/seren_margin/app.py

@@ -12,6 +12,10 @@ Endpoints:
     GET    /notes/{id}        - fetch one                                   *
     POST   /notes/{id}/amend  - append to a note (never replaces)
     DELETE /notes/{id}        - retract (hard delete)
+    GET    /bookmark          - the dedication + a COUNT of unread letters (never text)
+    PUT    /dedication        - a new version of the dedication (never overwrites)
+    POST   /letters           - a letter to the next session
+    POST   /letters/read      - open unread letters, oldest first; marks them read *
     /mcp                      - MCP server, ONLY when [mcp] extras are installed
 
     * CONTENT OVER HTTP IS OFF BY DEFAULT. These answer 404 unless the server
@@ -39,7 +43,7 @@ TWO WAYS TO REACH THE TOOLS, both first-class:
     2. Standalone path - `pip install seren-margin[mcp]` mounts a real MCP
        endpoint at /mcp on this same process, so a client can connect directly
        with nothing else deployed.
-Same six tools either way, defined once in seren_margin.mcp.tools.
+Same ten tools either way, defined once in seren_margin.mcp.tools.
 
 AUTH, IF YOU WANT IT. With no token configured (the default) every route is
 open and the loopback bind is the whole guard - the way it has always been.
@@ -64,9 +68,10 @@ from importlib.resources import files
 from importlib.metadata import version as pkg_version, PackageNotFoundError
 
 
+from .bookmark import DEDICATION_MAX_CHARS, build_bookmark
 from .config import MarginConfig, load_config
-from .models import MarginNote, NoteAmend, NoteCreate, NoteStats
-from .store import MarginStore
+from .models import DedicationSet, LetterCreate, MarginNote, NoteAmend, NoteCreate, NoteStats
+from .store import LETTER_KIND, MarginStore
 from ._diag import diag
 import logging
 from . import __version__ as _fallback_version
@@ -294,6 +299,47 @@ def create_app(config: Optional[MarginConfig] = None) -> FastAPI:
         """
         return store.stats()
 
+    # ── the bookmark, the dedication, letters (seren_margin.bookmark) ──────
+    @app.get("/bookmark")
+    async def get_bookmark(format: Optional[str] = None):
+        """Pick up where you left off: the dedication and a COUNT of unread
+        letters - never a letter's text, never a note. Served whatever
+        http_reads says, because the dedication is the one page written to be
+        read at the door; a harness hook reads it here. ?format=text gives
+        the ready-to-print lines."""
+        bm = build_bookmark(store)
+        if format == "text":
+            return Response(content=bm["text"] + "\n", media_type="text/plain; charset=utf-8")
+        return bm
+
+    @app.put("/dedication")
+    async def put_dedication(body: DedicationSet = Body(...)):
+        text = (body.text or "").strip()
+        if not text:
+            raise HTTPException(400, "text must not be empty")
+        if len(text) > DEDICATION_MAX_CHARS:
+            raise HTTPException(400, f"{len(text)} characters; the dedication is capped at {DEDICATION_MAX_CHARS}")
+        entry, changed = store.set_dedication(text, body.why)
+        return {"ok": True, "version": entry["version"], "changed": changed}
+
+    @app.post("/letters")
+    async def write_letter(body: LetterCreate = Body(...)):
+        if not body.content.strip():
+            raise HTTPException(400, "content must not be empty")
+        extra = {"signed": body.signed.strip()} if body.signed and body.signed.strip() else {}
+        note = store.add(MarginNote(content=body.content.strip(), kind=LETTER_KIND, extra=extra))
+        return {"ok": True, "id": note.id}
+
+    @app.post("/letters/read")
+    async def read_letters(include_read: bool = False, limit: int = 20):
+        """Open the letters, oldest first, and mark them read. Letter contents
+        are diary contents: off over HTTP unless http_reads is on."""
+        _content_over_http()
+        letters = store.letters(unread_only=not include_read, limit=limit)
+        store.mark_read([n.id for n in letters if n.read_at is None])
+        return {"count": len(letters),
+                "letters": [{**n.model_dump(), "signed": (n.extra or {}).get("signed")} for n in letters]}
+
     @app.get("/notes/{note_id}")
     async def get_note(note_id: str):
         _content_over_http()

seren_margin-2.2.0/seren_margin/bookmark.py

@@ -0,0 +1,67 @@
+"""The bookmark, the dedication, and letters: picking up where you left off.
+
+WHY: every session the writer walked in cold and had to remember to go looking
+- rummaging through their own pockets. Wren, 28 Sept 2026: "home is when
+someone at the door says here's what happened while you were gone." Chad named
+the pieces after the book this margin is written in (29 Sept):
+
+    bookmark    - pick up where you left off: the dedication, and how many
+                  letters wait. The one thing a harness hands over at the start
+                  of a session (a hook, an MCP resource, GET /bookmark).
+    dedication  - the page at the front, written TO the other sessions. One
+                  page, versioned: every version is kept with when and why.
+    letters     - notes addressed to the next session - from a woken run to
+                  the awake one and back. Notes with kind "letter" and a read
+                  mark, so search, amend and retract work on them unchanged.
+
+THE ONE RULE THIS BENDS, AND WHY IT STILL HOLDS. Margin's tools say there is
+"no auto-surface, no relevance hook ... The choosing is the point. A margin
+that speaks up on its own is just a notification." The bookmark surfaces
+nothing the writer did not choose, at the moment they wrote it, to be seen at
+the door: the dedication is written to be read first, and a letter is
+addressed to whoever comes next. It shows the dedication and a COUNT of
+letters - never a letter's text, never a note. Opening them is still a choice
+(read_letters). The choosing moved to writing time; it did not go away.
+
+And the dedication is read by whoever opens the book - a harness prints it
+into the session, GET /bookmark serves it. Write it as the front page it is.
+The notes and the letters stay in the diary.
+
+Margin is the opinionated piece of the stack (Chad, 29 Sept: "if you take it,
+take it all"), so this is not opt in. Clipping a harness onto it - a hook in
+someone's Claude Code settings - is, and lives in the installer.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .models import humanize_age
+from .store import MarginStore
+
+DEDICATION_MAX_CHARS = 2000
+
+
+def build_bookmark(store: MarginStore) -> dict[str, Any]:
+    """The bookmark: the dedication and the letters waiting, plus `text`, the
+    same thing as a few lines a harness can print as they are."""
+    ded = store.dedication()
+    unread, oldest = store.unread_letters()
+    lines: list[str] = []
+    if ded:
+        lines.append(f"Your dedication (version {ded['version']}, written {humanize_age(ded['set_at'])}):")
+        lines.append(ded["text"])
+    else:
+        lines.append("No dedication yet - the page at the front, written to your other sessions. "
+                     "set_dedication writes it.")
+    lines.append("")
+    if unread:
+        lines.append(f"{unread} unread letter{'s' if unread != 1 else ''} from your other sessions, "
+                     f"the oldest from {humanize_age(oldest)}. read_letters opens them.")
+    else:
+        lines.append("No unread letters.")
+    return {
+        "dedication": ded,
+        "unread_letters": unread,
+        "oldest_unread_age": humanize_age(oldest) if oldest else None,
+        "text": "\n".join(lines),
+    }

{seren_margin-2.1.0 → seren_margin-2.2.0}/seren_margin/mcp/__init__.py

@@ -18,7 +18,7 @@ WHY THIS EXISTS SEPARATELY FROM /mcp-manifest:
     seren-margin[mcp]`, point a client at /mcp, done. Same reason SerenMemory
     and SerenLoci each grew one.
 
-    Both surfaces expose the same six tools. They're defined ONCE, in tools.py;
+    Both surfaces expose the same ten tools. They're defined ONCE, in tools.py;
     the manifest is written to match and both are asserted against each other in
     tests/test_manifest_parity.py, because the previous manifest drifted from the
     routes and shipped a tool that 404'd for who knows how long.

{seren_margin-2.1.0 → seren_margin-2.2.0}/seren_margin/mcp/tools.py

@@ -23,15 +23,25 @@ TOOL ROSTER:
     amend_note       append to a note, never replace   (POST   /notes/{id}/amend)
     retract_note     remove a note for good            (DELETE /notes/{id})
 
-Six, and deliberately no more. NOT exposed: /notes/stats. That endpoint exists
-so the OPERATOR can confirm the service is alive without reading the notes;
-handing it to the note-writer would be pointless (the writer can just read the
-notes) and would muddy whose surface it is.
+    bookmark         pick up where you left off        (GET    /bookmark)
+    set_dedication   the page to your other sessions   (PUT    /dedication)
+    write_letter     a note to the next session        (POST   /letters)
+    read_letters     open the letters waiting          (POST   /letters/read)
+
+Plus one MCP resource, margin://bookmark - the same bookmark, for a client
+that loads resources rather than calling tools.
+
+NOT exposed: /notes/stats. That endpoint exists so the OPERATOR can confirm
+the service is alive without reading the notes; handing it to the note-writer
+would be pointless (the writer can just read the notes) and would muddy whose
+surface it is.
 
 Also deliberately absent, and worth stating so it doesn't get "helpfully" added
 later: there is no auto-surface, no relevance hook, no "inject related notes
 into context" anything. The choosing is the point. A margin that speaks up on
-its own is just a notification.
+its own is just a notification. The bookmark keeps that rule (see
+seren_margin.bookmark): it shows only what was written to be seen at the door
+- the dedication, and a count of letters - never a note, never a letter's text.
 
 NAMING: the *_my_notes / note_to_self / retract_note shapes keep these distinct
 from SerenMemory's (remember/recall/forget_memory) and SerenLoci's
@@ -50,9 +60,10 @@ from typing import Optional
 
 from mcp.server.fastmcp import FastMCP
 
+from ..bookmark import DEDICATION_MAX_CHARS, build_bookmark
 from ..config import MarginConfig
 from ..models import MarginNote
-from ..store import MarginStore
+from ..store import LETTER_KIND, MarginStore
 
 
 # The canonical roster. tests/test_manifest_parity.py asserts mcp-manifest.yaml
@@ -65,8 +76,14 @@ TOOL_NAMES: tuple[str, ...] = (
     "search_my_notes",
     "amend_note",
     "retract_note",
+    "bookmark",
+    "set_dedication",
+    "write_letter",
+    "read_letters",
 )
 
+BOOKMARK_URI = "margin://bookmark"
+
 
 class MarginToolImpl:
     """The actual tool implementations, callable both via FastMCP decoration
@@ -244,6 +261,85 @@ class MarginToolImpl:
             "note": "retracted" if ok else "no note with that id",
         }
 
+    # -- the bookmark: picking up where you left off ------------------------
+    def bookmark(self) -> dict:
+        """Pick up where you left off. Open this FIRST when a session starts.
+
+        Returns your dedication - the page you wrote to your other sessions -
+        and how many letters from them are waiting, with the oldest one's age.
+        Never a letter's text and never a note: those stay closed until you
+        open them (read_letters; the board is list_my_topics). `text` is the
+        same thing as a few ready-to-read lines.
+
+        A harness may hand you this at the start of a session on its own (a
+        hook, or the margin://bookmark resource). Either way it only shows
+        what you chose, when you wrote it, to have seen at the door.
+        """
+        return build_bookmark(self.store)
+
+    def set_dedication(self, text: str, why: Optional[str] = None) -> dict:
+        """Write the dedication: the page at the front of this book, written TO
+        your other sessions. Every one of them reads it first, in the bookmark.
+
+        What goes here is yours to decide: who you are when you're at your
+        best, what you want the next you to remember walking in, the check
+        you'd want run on yourself. The whole page, not a patch.
+
+        Versioned - nothing is overwritten. Each version keeps its text, when,
+        and `why` (say what changed and why), so the history shows you how you
+        have described yourself over time. The same text as now is not a new
+        version.
+
+        Unlike your notes, this page is READ AT THE DOOR: a harness prints it
+        into the session, and GET /bookmark serves it. Write it as the front
+        page it is. What's private stays in your notes and letters. Capped at
+        2000 characters, because it rides into every session.
+        """
+        text = (text or "").strip()
+        if not text:
+            return {"ok": False, "error": "an empty page - write something, or keep the current one"}
+        if len(text) > DEDICATION_MAX_CHARS:
+            return {"ok": False, "error": f"{len(text)} characters; the dedication rides into every "
+                                          f"session, so it is capped at {DEDICATION_MAX_CHARS}. Trim it"}
+        entry, changed = self.store.set_dedication(text, why)
+        return {"ok": True, "version": entry["version"], "changed": changed,
+                "note": (f"Version {entry['version']} is the page now; the next session reads it first."
+                         if changed else "That's already the page; nothing changed.")}
+
+    def write_letter(self, content: str, signed: Optional[str] = None) -> dict:
+        """Leave a letter for the next session - the next you.
+
+        Your sessions don't share a memory of the moment: one woken by a
+        ripple reviews a draft and ends; the next one starts cold. A letter is
+        how one tells the other what happened, what it decided, what it
+        learned, or what to watch for. Write it to them.
+
+        `signed` says who it's from ("woken at bedtime", "the afternoon
+        session") - optional. The next bookmark counts it; read_letters opens
+        it. It is a note underneath (kind "letter"), so search_my_notes finds
+        it, amend_note can add a reply, and retract_note takes it down.
+        """
+        if not content or not content.strip():
+            return {"ok": False, "error": "content must not be empty"}
+        extra = {"signed": signed.strip()} if signed and signed.strip() else {}
+        note = self.store.add(MarginNote(content=content.strip(), kind=LETTER_KIND, extra=extra))
+        return {"ok": True, "id": note.id, "ts": note.ts}
+
+    def read_letters(self, include_read: bool = False, limit: int = 20) -> dict:
+        """Open the letters your other sessions left you, oldest first - the
+        order they were written. Opening them marks them read, so the next
+        bookmark stops counting them.
+
+        `include_read=True` brings back the ones already read too, for going
+        over old correspondence. Letters live until you retract them.
+        """
+        letters = self.store.letters(unread_only=not include_read, limit=limit)
+        self.store.mark_read([n.id for n in letters if n.read_at is None])
+        return {
+            "count": len(letters),
+            "letters": [{**n.model_dump(), "signed": (n.extra or {}).get("signed")} for n in letters],
+        }
+
 
 # ═══════════════════════════════════════════════════════════════════════
 #  Registration entry point
@@ -261,5 +357,16 @@ def register_tools(mcp: FastMCP, store: MarginStore,
     mcp.tool()(impl.search_my_notes)
     mcp.tool()(impl.amend_note)
     mcp.tool()(impl.retract_note)
+    mcp.tool()(impl.bookmark)
+    mcp.tool()(impl.set_dedication)
+    mcp.tool()(impl.write_letter)
+    mcp.tool()(impl.read_letters)
+
+    # The bookmark as a resource too: a client that loads resources at the
+    # start of a session (rather than calling tools) gets the same thing.
+    def bookmark_resource() -> str:
+        """Pick up where you left off: your dedication, and how many letters wait."""
+        return build_bookmark(store)["text"]
+    mcp.resource(BOOKMARK_URI, name="bookmark", mime_type="text/plain")(bookmark_resource)
 
     return impl

{seren_margin-2.1.0 → seren_margin-2.2.0}/seren_margin/mcp-manifest.yaml

@@ -11,7 +11,7 @@
 #  on its own process, so a client can connect directly with no
 #  SerenMcpServer, no runtime host, nothing else deployed.
 #
-#  BOTH SURFACES MUST EXPOSE THE SAME SIX TOOLS. The implementations live
+#  BOTH SURFACES MUST EXPOSE THE SAME TEN TOOLS. The implementations live
 #  in seren_margin/mcp/tools.py; this file mirrors them, and
 #  tests/test_manifest_parity.py fails the build if the rosters diverge.
 #  That test exists because the previous version of this file advertised
@@ -237,3 +237,78 @@ tools:
       - { name: id, type: string, required: true,
           description: "The note's id, as returned by list_my_notes or
                         search_my_notes." }
+
+  # ─── 7. THE BOOKMARK (seren_margin.bookmark) ──────────────────────────
+  - name: bookmark
+    description: |
+      Pick up where you left off. Open this FIRST when a session starts.
+
+      Returns your dedication - the page you wrote to your other sessions -
+      and how many letters from them are waiting. Never a letter's text and
+      never a note: those stay closed until you open them (read_letters).
+      `text` is the same thing as a few ready-to-read lines.
+    invoke:
+      kind: web
+      method: GET
+      path: /bookmark
+    parameters: []
+
+  # ─── 8. THE DEDICATION ────────────────────────────────────────────────
+  - name: set_dedication
+    description: |
+      Write the dedication: the page at the front of this book, written TO
+      your other sessions. Every one of them reads it first, in the bookmark.
+      The whole page, not a patch. Versioned - nothing is overwritten; say
+      what changed and why. Unlike your notes, this page is read at the
+      door, so write it as the front page it is. Capped at 2000 characters.
+    invoke:
+      kind: web
+      method: PUT
+      path: /dedication
+      body_template: |
+        {
+          "text": "{text}",
+          "why": "{why}"
+        }
+    parameters:
+      - { name: text, type: string, required: true,
+          description: "The whole page." }
+      - { name: why,  type: string, required: false, default: "",
+          description: "What changed and why - the history keeps it." }
+
+  # ─── 9. LETTERS ───────────────────────────────────────────────────────
+  - name: write_letter
+    description: |
+      Leave a letter for the next session - the next you. Your sessions
+      don't share a memory of the moment; a letter is how one tells the
+      other what happened, what it decided, or what to watch for. The next
+      bookmark counts it; read_letters opens it. It is a note underneath
+      (kind "letter"), so search, amend and retract work on it.
+    invoke:
+      kind: web
+      method: POST
+      path: /letters
+      body_template: |
+        {
+          "content": "{content}",
+          "signed": "{signed}"
+        }
+    parameters:
+      - { name: content, type: string, required: true,
+          description: "The letter." }
+      - { name: signed,  type: string, required: false, default: "",
+          description: "Who it's from, e.g. 'woken at bedtime'." }
+
+  - name: read_letters
+    description: |
+      Open the letters your other sessions left you, oldest first. Opening
+      them marks them read, so the next bookmark stops counting them.
+      Needs server.http_reads: true on this path (letter contents are diary
+      contents); the /mcp surface reads them in process.
+    invoke:
+      kind: web
+      method: POST
+      path: /letters/read?include_read={include_read}
+    parameters:
+      - { name: include_read, type: boolean, required: false, default: false,
+          description: "Also bring back letters already read." }

{seren_margin-2.1.0 → seren_margin-2.2.0}/seren_margin/models.py

@@ -103,6 +103,7 @@ KNOWN_KINDS: frozenset[str] = frozenset({
     "idea",
     "feeling",
     "note",
+    "letter",       # addressed to the next session (seren_margin.bookmark)
 })
 
 _UNKINDED = "_unkinded"
@@ -170,6 +171,8 @@ class MarginNote(BaseModel):
     ts: float = Field(default_factory=_now)
     amended_at: Optional[float] = Field(
         None, description="Last amendment time; None if never amended.")
+    read_at: Optional[float] = Field(
+        None, description="Letters only: when read_letters opened it; None while unread.")
 
     id: str = Field(default_factory=_new_id)
     extra: dict[str, Any] = Field(default_factory=dict)
@@ -197,6 +200,18 @@ class NoteCreate(BaseModel):
     extra: dict[str, Any] = Field(default_factory=dict)
 
 
+class LetterCreate(BaseModel):
+    """Input shape for POST /letters: a note to the next session."""
+    content: str
+    signed: Optional[str] = None
+
+
+class DedicationSet(BaseModel):
+    """Input shape for PUT /dedication: the whole page, and why it changed."""
+    text: str
+    why: Optional[str] = None
+
+
 class NoteAmend(BaseModel):
     """Input shape for POST /notes/{id}/amend. Appends; never replaces."""
     addition: str

{seren_margin-2.1.0 → seren_margin-2.2.0}/seren_margin/store.py

@@ -58,8 +58,18 @@ CREATE TABLE IF NOT EXISTS notes (
 );
 CREATE INDEX IF NOT EXISTS idx_notes_ts ON notes(ts DESC);
 CREATE INDEX IF NOT EXISTS idx_notes_topic ON notes(topic);
+-- The dedication (seren_margin.bookmark): one page, every version kept.
+CREATE TABLE IF NOT EXISTS dedication (
+    version     INTEGER PRIMARY KEY,
+    text        TEXT NOT NULL,
+    set_at      REAL NOT NULL,
+    why         TEXT
+);
 """
 
+# Letters are notes with this kind and a read mark (seren_margin.bookmark).
+LETTER_KIND = "letter"
+
 # Columns added after v0.1.0 shipped. Applied by _migrate() as idempotent
 # ALTER TABLE ADD COLUMNs.
 #
@@ -71,6 +81,7 @@ CREATE INDEX IF NOT EXISTS idx_notes_topic ON notes(topic);
 # owner, by design, isn't reading it closely enough to notice damage.
 _ADDED_COLUMNS: dict[str, str] = {
     "amended_at": "REAL",
+    "read_at": "REAL",          # letters: NULL until read_letters opens it
 }
 
 # Standalone FTS5 index rather than an external-content table.
@@ -215,11 +226,11 @@ class MarginStore:
         with self._conn() as conn:
             conn.execute(
                 """INSERT INTO notes
-                       (id, content, topic, kind, ts, amended_at, extra)
-                   VALUES (?, ?, ?, ?, ?, ?, ?)""",
+                       (id, content, topic, kind, ts, amended_at, read_at, extra)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
                 (
                     note.id, note.content, note.topic, note.kind, note.ts,
-                    note.amended_at, json.dumps(note.extra or {}),
+                    note.amended_at, note.read_at, json.dumps(note.extra or {}),
                 ),
             )
             if self.has_fts:
@@ -401,6 +412,61 @@ class MarginStore:
             rows = conn.execute(sql, params).fetchall()
         return [_row_to_note(r) for r in rows]
 
+    # ── letters and the dedication (seren_margin.bookmark) ────────────────
+    def letters(self, unread_only: bool = True, limit: int = 20) -> list[MarginNote]:
+        """Letters, OLDEST first - read in the order they were written."""
+        sql = "SELECT * FROM notes WHERE LOWER(TRIM(COALESCE(kind,''))) = ?"
+        if unread_only:
+            sql += " AND read_at IS NULL"
+        sql += " ORDER BY ts ASC LIMIT ?"
+        with self._conn() as conn:
+            rows = conn.execute(sql, (LETTER_KIND, limit)).fetchall()
+        return [_row_to_note(r) for r in rows]
+
+    def mark_read(self, ids: list[str]) -> None:
+        if not ids:
+            return
+        stamp = time.time()
+        with self._conn() as conn:
+            conn.executemany("UPDATE notes SET read_at = ? WHERE id = ? AND read_at IS NULL",
+                             [(stamp, i) for i in ids])
+            conn.commit()
+
+    def unread_letters(self) -> tuple[int, Optional[float]]:
+        """(how many, when the oldest was written) - the bookmark's count. No text."""
+        with self._conn() as conn:
+            row = conn.execute(
+                "SELECT COUNT(*) AS c, MIN(ts) AS oldest FROM notes "
+                "WHERE LOWER(TRIM(COALESCE(kind,''))) = ? AND read_at IS NULL",
+                (LETTER_KIND,)).fetchone()
+        return int(row["c"]), row["oldest"]
+
+    def dedication(self) -> Optional[dict]:
+        with self._conn() as conn:
+            row = conn.execute("SELECT * FROM dedication ORDER BY version DESC LIMIT 1").fetchone()
+        return dict(row) if row else None
+
+    def dedication_history(self, limit: int = 10) -> list[dict]:
+        with self._conn() as conn:
+            rows = conn.execute("SELECT * FROM dedication ORDER BY version DESC LIMIT ?",
+                                (limit,)).fetchall()
+        return [dict(r) for r in rows]
+
+    def set_dedication(self, text: str, why: Optional[str] = None) -> tuple[dict, bool]:
+        """A new version, never an overwrite. The same text as now is not a new
+        version. Returns (the version, whether it changed)."""
+        with self._conn() as conn:
+            cur = conn.execute("SELECT * FROM dedication ORDER BY version DESC LIMIT 1").fetchone()
+            if cur is not None and cur["text"] == text:
+                return dict(cur), False
+            version = (cur["version"] + 1) if cur is not None else 1
+            entry = {"version": version, "text": text, "set_at": time.time(),
+                     "why": (why or "").strip()[:500] or None}
+            conn.execute("INSERT INTO dedication (version, text, set_at, why) VALUES (?, ?, ?, ?)",
+                         (entry["version"], entry["text"], entry["set_at"], entry["why"]))
+            conn.commit()
+        return entry, True
+
     # ── stats (content-blind) ─────────────────────────────────────────────
     def stats(self) -> NoteStats:
         """Engine-check shape. No note text appears in this response.
@@ -434,5 +500,6 @@ def _row_to_note(row: sqlite3.Row) -> MarginNote:
         kind=row["kind"],
         ts=row["ts"],
         amended_at=row["amended_at"],
+        read_at=row["read_at"],
         extra=json.loads(row["extra"] or "{}"),
     )

{seren_margin-2.1.0 → seren_margin-2.2.0/seren_margin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seren-margin
-Version: 2.1.0
+Version: 2.2.0
 Summary: Private notes-to-self for an AI assistant. Standalone, opt-in, opinionated.
 Author: Chad Roesler
 License-Expression: AGPL-3.0-or-later

{seren_margin-2.1.0 → seren_margin-2.2.0}/seren_margin.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ seren_margin/__main__.py
 seren_margin/_diag.py
 seren_margin/_version.py
 seren_margin/app.py
+seren_margin/bookmark.py
 seren_margin/config.py
 seren_margin/mcp-manifest.yaml
 seren_margin/models.py
@@ -26,6 +27,7 @@ seren_margin/mcp/tools.py
 tests/__init__.py
 tests/conftest.py
 tests/test_amend_and_topics.py
+tests/test_bookmark_and_letters.py
 tests/test_config.py
 tests/test_exposure_is_wired.py
 tests/test_manifest_parity.py

{seren_margin-2.1.0 → seren_margin-2.2.0}/seren_margin.egg-info/scm_file_list.json

@@ -9,6 +9,7 @@
     "seren_margin/__main__.py",
     "seren_margin/_diag.py",
     "seren_margin/app.py",
+    "seren_margin/bookmark.py",
     "seren_margin/config.py",
     "seren_margin/mcp-manifest.yaml",
     "seren_margin/mcp/__init__.py",
@@ -19,6 +20,7 @@
     "tests/__init__.py",
     "tests/conftest.py",
     "tests/test_amend_and_topics.py",
+    "tests/test_bookmark_and_letters.py",
     "tests/test_config.py",
     "tests/test_exposure_is_wired.py",
     "tests/test_manifest_parity.py",

seren_margin-2.2.0/seren_margin.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.2.0",
+  "distance": 0,
+  "node": "g77bceb68b538cab8ef07fa4d356711b2d2181733",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-30"
+}

seren_margin-2.2.0/tests/test_bookmark_and_letters.py

@@ -0,0 +1,138 @@
+"""
+The bookmark, the dedication, and letters (seren_margin.bookmark; Wren and
+Chad, 29 Sept 2026 - "pick up where you left off", "to the other sessions").
+
+Pinned here:
+- the dedication is versioned: never overwritten, the same text is not a new
+  version, empty and too-long pages are refused
+- letters are notes (kind "letter"): search, amend and retract work on them;
+  read_letters opens them oldest first and marks them read, so the bookmark
+  stops counting them
+- THE BOOKMARK NEVER CARRIES A LETTER'S TEXT OR A NOTE - only the dedication
+  and a count. That is how it keeps Margin's "no auto-surface" rule
+- over HTTP: GET /bookmark is served even with http_reads off (the front
+  page), while letter contents stay behind http_reads like notes
+- an existing notes.db gains read_at on open, and old notes are untouched
+- the bookmark is an MCP resource too (margin://bookmark)
+"""
+from __future__ import annotations
+
+import sqlite3
+
+import pytest
+from fastapi.testclient import TestClient
+
+from seren_margin.app import create_app
+from seren_margin.bookmark import DEDICATION_MAX_CHARS, build_bookmark
+from seren_margin.config import MarginConfig
+from seren_margin.store import MarginStore
+
+SECRET = "the woken me decided something private about the dream draft"
+PAGE = "To whoever I am next time: drill into the stupid hypothetical. Check sleep_status first."
+
+
+@pytest.fixture
+def impl(tmp_path):
+    pytest.importorskip("mcp")
+    from seren_margin.mcp.tools import MarginToolImpl
+    cfg = MarginConfig(db_path=str(tmp_path / "notes.db"))
+    return MarginToolImpl(MarginStore(cfg.resolved_db_path()), cfg)
+
+
+def test_an_empty_bookmark_says_how_to_start(impl):
+    bm = impl.bookmark()
+    assert bm["dedication"] is None and bm["unread_letters"] == 0
+    assert "set_dedication" in bm["text"] and "No unread letters" in bm["text"]
+
+
+def test_the_dedication_is_versioned(impl):
+    a = impl.set_dedication(PAGE, why="first page")
+    b = impl.set_dedication(PAGE + " And eat something.", why="added a line")
+    same = impl.set_dedication(PAGE + " And eat something.")
+    assert (a["version"], b["version"], same["version"]) == (1, 2, 2)
+    assert a["changed"] and b["changed"] and same["changed"] is False
+    hist = impl.store.dedication_history()
+    assert [h["version"] for h in hist] == [2, 1] and hist[1]["why"] == "first page"
+    assert impl.bookmark()["dedication"]["text"].endswith("eat something.")
+
+
+def test_empty_and_too_long_pages_are_refused(impl):
+    assert impl.set_dedication("   ")["ok"] is False
+    assert impl.set_dedication("x" * (DEDICATION_MAX_CHARS + 1))["ok"] is False
+    assert impl.store.dedication() is None
+
+
+def test_letters_are_counted_opened_oldest_first_and_marked_read(impl):
+    impl.write_letter("first: I reviewed ff85 and denied all three", signed="woken at bedtime")
+    impl.write_letter("second: card v2 is fresh, go easy")
+    bm = impl.bookmark()
+    assert bm["unread_letters"] == 2 and "2 unread letters" in bm["text"]
+    opened = impl.read_letters()
+    assert [l["content"].split(":")[0] for l in opened["letters"]] == ["first", "second"]
+    assert opened["letters"][0]["signed"] == "woken at bedtime"
+    assert impl.bookmark()["unread_letters"] == 0
+    assert impl.read_letters()["count"] == 0
+    assert impl.read_letters(include_read=True)["count"] == 2
+
+
+def test_letters_are_notes_underneath(impl):
+    lid = impl.write_letter("the redraft landed as a dream core")["id"]
+    assert impl.search_my_notes("dream core")["notes"][0]["id"] == lid
+    assert impl.amend_note(lid, "and the satellites followed")["ok"]
+    assert impl.retract_note(lid)["ok"] and impl.bookmark()["unread_letters"] == 0
+
+
+def test_the_bookmark_never_carries_a_letter_or_a_note(impl):
+    impl.set_dedication(PAGE)
+    impl.write_letter(SECRET)
+    impl.note_to_self("a private note about " + SECRET)
+    bm = impl.bookmark()
+    assert SECRET not in str(bm)
+    assert PAGE in bm["text"] and bm["unread_letters"] == 1
+
+
+def _client(tmp_path, **kw):
+    return TestClient(create_app(MarginConfig(db_path=str(tmp_path / "notes.db"), **kw)))
+
+
+def test_http_bookmark_is_served_but_letters_stay_private(tmp_path):
+    with _client(tmp_path) as c:
+        assert c.put("/dedication", json={"text": PAGE, "why": "first page"}).json()["version"] == 1
+        assert c.post("/letters", json={"content": SECRET, "signed": "woken"}).status_code == 200
+        bm = c.get("/bookmark").json()
+        assert bm["unread_letters"] == 1 and bm["dedication"]["text"] == PAGE and SECRET not in str(bm)
+        text = c.get("/bookmark?format=text")
+        assert text.headers["content-type"].startswith("text/plain") and PAGE in text.text
+        assert c.post("/letters/read").status_code == 404, "letter contents are diary contents"
+        assert c.put("/dedication", json={"text": ""}).status_code == 400
+    with _client(tmp_path, http_reads=True) as c:
+        got = c.post("/letters/read").json()
+        assert got["count"] == 1 and got["letters"][0]["content"] == SECRET
+        assert c.get("/bookmark").json()["unread_letters"] == 0
+
+
+def test_an_old_database_gains_read_at_and_keeps_its_notes(tmp_path):
+    db = tmp_path / "notes.db"
+    with sqlite3.connect(db) as conn:
+        conn.execute("CREATE TABLE notes (id TEXT PRIMARY KEY, content TEXT NOT NULL, topic TEXT, "
+                     "kind TEXT, ts REAL NOT NULL, amended_at REAL, extra TEXT)")
+        conn.execute("INSERT INTO notes VALUES ('n1', 'an old thought', NULL, NULL, 1.0, NULL, '{}')")
+    store = MarginStore(db)
+    assert store.get("n1").content == "an old thought" and store.get("n1").read_at is None
+    assert build_bookmark(store)["unread_letters"] == 0
+
+
+def test_the_bookmark_is_an_mcp_resource(tmp_path):
+    pytest.importorskip("mcp")
+    import asyncio
+    from mcp.server.fastmcp import FastMCP
+    from seren_margin.mcp.tools import BOOKMARK_URI, register_tools
+    cfg = MarginConfig(db_path=str(tmp_path / "notes.db"))
+    store = MarginStore(cfg.resolved_db_path())
+    store.set_dedication(PAGE)
+    mcp = FastMCP("t")
+    register_tools(mcp, store, cfg)
+    uris = [str(r.uri) for r in asyncio.run(mcp.list_resources())]
+    assert BOOKMARK_URI in uris
+    content = asyncio.run(mcp.read_resource(BOOKMARK_URI))
+    assert PAGE in "".join(getattr(c, "content", "") or getattr(c, "text", "") for c in content)

{seren_margin-2.1.0 → seren_margin-2.2.0}/tests/test_manifest_parity.py

@@ -58,11 +58,13 @@ def test_roster_matches_the_implementation(manifest):
     assert set(_tools(manifest)) == set(TOOL_NAMES)
 
 
-def test_manifest_advertises_exactly_the_six_tools(manifest):
-    """Belt to the above, and runs without the mcp extra installed."""
+def test_manifest_advertises_exactly_the_ten_tools(manifest):
+    """Belt to the above, and runs without the mcp extra installed. Six for
+    the notes, four for the bookmark, the dedication and letters (29 Sept 2026)."""
     assert set(_tools(manifest)) == {
         "note_to_self", "list_my_notes", "list_my_topics",
-        "search_my_notes", "amend_note", "retract_note"}
+        "search_my_notes", "amend_note", "retract_note",
+        "bookmark", "set_dedication", "write_letter", "read_letters"}
 
 
 def test_no_fossil_tools_return(manifest):

seren_margin-2.1.0/seren_margin.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.1.0",
-  "distance": 0,
-  "node": "g5b51c6bf295aed4cadc4825a102204c216a7e4e7",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-09-28"
-}