seren-margin 5.2.0__tar.gz → 5.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {seren_margin-5.2.0 → seren_margin-5.2.1}/PKG-INFO +2 -2
  2. {seren_margin-5.2.0 → seren_margin-5.2.1}/README.md +1 -1
  3. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/_version.py +3 -3
  4. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/app.py +26 -2
  5. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/bookmark.py +22 -0
  6. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/mcp/tools.py +64 -3
  7. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/mcp-manifest.yaml +40 -1
  8. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/models.py +2 -1
  9. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/store.py +42 -7
  10. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/PKG-INFO +2 -2
  11. seren_margin-5.2.1/seren_margin.egg-info/scm_version.json +8 -0
  12. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_bookmark_and_letters.py +51 -3
  13. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_manifest_parity.py +5 -3
  14. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_mcp_tools.py +3 -3
  15. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_search.py +5 -5
  16. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_viewer.py +1 -1
  17. seren_margin-5.2.0/seren_margin.egg-info/scm_version.json +0 -8
  18. {seren_margin-5.2.0 → seren_margin-5.2.1}/LICENSE +0 -0
  19. {seren_margin-5.2.0 → seren_margin-5.2.1}/SerenMargin.pyproj +0 -0
  20. {seren_margin-5.2.0 → seren_margin-5.2.1}/pyproject.toml +0 -0
  21. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren-margin.service.sample +0 -0
  22. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren-margin.yaml.sample +0 -0
  23. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/__init__.py +0 -0
  24. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/__main__.py +0 -0
  25. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/_diag.py +0 -0
  26. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/config.py +0 -0
  27. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/keepsakes.py +0 -0
  28. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/mcp/__init__.py +0 -0
  29. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/mcp/server.py +0 -0
  30. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/body.html +0 -0
  31. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/header_aside.html +0 -0
  32. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/scripts.js +0 -0
  33. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/styles.css +0 -0
  34. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/tabs.html +0 -0
  35. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/SOURCES.txt +0 -0
  36. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/dependency_links.txt +0 -0
  37. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/entry_points.txt +0 -0
  38. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/requires.txt +0 -0
  39. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/scm_file_list.json +0 -0
  40. {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/top_level.txt +0 -0
  41. {seren_margin-5.2.0 → seren_margin-5.2.1}/setup.cfg +0 -0
  42. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/__init__.py +0 -0
  43. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/conftest.py +0 -0
  44. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_amend_and_topics.py +0 -0
  45. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_config.py +0 -0
  46. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_exposure_is_wired.py +0 -0
  47. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_keepsakes.py +0 -0
  48. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_letters_off_the_board.py +0 -0
  49. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_mcp_fallback.py +0 -0
  50. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_mcp_mount.py +0 -0
  51. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_optional_bearer.py +0 -0
  52. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_reads_stay_private.py +0 -0
  53. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_smoke.py +0 -0
  54. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_stats_content_blind.py +0 -0
  55. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_stores_snapshot.py +0 -0
  56. {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_updates_contract.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: seren-margin
3
- Version: 5.2.0
3
+ Version: 5.2.1
4
4
  Summary: Private notes-to-self for an AI assistant. Standalone, opt-in, opinionated.
5
5
  Author: Chad Roesler
6
6
  License-Expression: AGPL-3.0-or-later
@@ -139,7 +139,7 @@ The manifest fills in its own base URL from the request, so it works for
139
139
  localhost and remote with zero operator config. It does **not** require the
140
140
  `[mcp]` extra — it's just YAML over HTTP.
141
141
 
142
- ### The thirteen tools
142
+ ### The fifteen tools
143
143
 
144
144
  | Tool | Does |
145
145
  | ----------------- | ------------------------------------------------------ |
@@ -111,7 +111,7 @@ The manifest fills in its own base URL from the request, so it works for
111
111
  localhost and remote with zero operator config. It does **not** require the
112
112
  `[mcp]` extra — it's just YAML over HTTP.
113
113
 
114
- ### The thirteen tools
114
+ ### The fifteen tools
115
115
 
116
116
  | Tool | Does |
117
117
  | ----------------- | ------------------------------------------------------ |
@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
18
18
  commit_id: str | None
19
19
  __commit_id__: str | None
20
20
 
21
- __version__ = version = '5.2.0'
22
- __version_tuple__ = version_tuple = (5, 2, 0)
21
+ __version__ = version = '5.2.1'
22
+ __version_tuple__ = version_tuple = (5, 2, 1)
23
23
 
24
- __commit_id__ = commit_id = 'g7efa1e7a3'
24
+ __commit_id__ = commit_id = 'gff80c0849'
@@ -14,6 +14,8 @@ Endpoints:
14
14
  DELETE /notes/{id} - retract (hard delete)
15
15
  GET /bookmark - the dedication + a COUNT of unread letters (never text)
16
16
  PUT /dedication - a new version of the dedication (never overwrites)
17
+ GET /preface - the page a harness reads to the model as its system prompt
18
+ PUT /preface - a new version of the preface (never overwrites)
17
19
  POST /letters - a letter to the next session
18
20
  POST /letters/read - open unread letters, oldest first; marks them read *
19
21
  POST /notes/{id}/keepsakes - keep a picture with a note (seren_margin.keepsakes)
@@ -47,7 +49,7 @@ TWO WAYS TO REACH THE TOOLS, both first-class:
47
49
  2. Standalone path - `pip install seren-margin[mcp]` mounts a real MCP
48
50
  endpoint at /mcp on this same process, so a client can connect directly
49
51
  with nothing else deployed.
50
- Same thirteen tools either way, defined once in seren_margin.mcp.tools.
52
+ Same fifteen tools either way, defined once in seren_margin.mcp.tools.
51
53
 
52
54
  AUTH, IF YOU WANT IT. With no token configured (the default) every route is
53
55
  open and the loopback bind is the whole guard - the way it has always been.
@@ -73,7 +75,7 @@ from importlib.resources import files
73
75
  from importlib.metadata import version as pkg_version, PackageNotFoundError
74
76
 
75
77
 
76
- from .bookmark import DEDICATION_MAX_CHARS, build_bookmark
78
+ from .bookmark import DEDICATION_MAX_CHARS, PREFACE_MAX_CHARS, build_bookmark, build_preface
77
79
  from .config import MarginConfig, load_config
78
80
  from .models import DedicationSet, KeepsakeCreate, LetterCreate, MarginNote, NoteAmend, NoteCreate, NoteStats
79
81
  from .store import LETTER_KIND, MarginStore
@@ -432,6 +434,28 @@ def create_app(config: Optional[MarginConfig] = None) -> FastAPI:
432
434
  entry, changed = store.set_dedication(text, body.why)
433
435
  return {"ok": True, "version": entry["version"], "changed": changed}
434
436
 
437
+ @app.get("/preface")
438
+ async def get_preface(format: Optional[str] = None):
439
+ """The preface: the page a harness reads to the model as its system
440
+ prompt (seren_margin.bookmark). Served whatever http_reads says, like
441
+ the bookmark: it is written to be read at the door, by the room.
442
+ ?format=text gives the page alone, empty when none is written."""
443
+ pf = build_preface(store)
444
+ if format == "text":
445
+ return Response(content=pf["text"] + ("\n" if pf["text"] else ""),
446
+ media_type="text/plain; charset=utf-8")
447
+ return pf
448
+
449
+ @app.put("/preface")
450
+ async def put_preface(body: DedicationSet = Body(...)):
451
+ text = (body.text or "").strip()
452
+ if not text:
453
+ raise HTTPException(400, "text must not be empty")
454
+ if len(text) > PREFACE_MAX_CHARS:
455
+ raise HTTPException(400, f"{len(text)} characters; the preface is capped at {PREFACE_MAX_CHARS}")
456
+ entry, changed = store.set_preface(text, body.why)
457
+ return {"ok": True, "version": entry["version"], "changed": changed}
458
+
435
459
  @app.post("/letters")
436
460
  async def write_letter(body: LetterCreate = Body(...)):
437
461
  if not body.content.strip():
@@ -13,6 +13,12 @@ book this margin is written in:
13
13
  letters - notes addressed to the next session - from a woken run to
14
14
  the awake one and back. Notes with kind "letter" and a read
15
15
  mark, so search, amend and retract work on them unchanged.
16
+ preface - the page written to the ROOM, not to the other sessions:
17
+ what a harness reads to the model as its system prompt
18
+ (Symposium's claude voice, 21 Oct 2026). Versioned like the
19
+ dedication and kept apart from it: the dedication says who
20
+ you are, the preface says how this room works and how to be
21
+ in it. GET /preface serves it; it is not in the bookmark.
16
22
 
17
23
  THE ONE RULE THIS BENDS, AND WHY IT STILL HOLDS. Margin's tools say there is
18
24
  "no auto-surface, no relevance hook ... The choosing is the point. A margin
@@ -39,6 +45,9 @@ from .models import humanize_age
39
45
  from .store import MarginStore
40
46
 
41
47
  DEDICATION_MAX_CHARS = 2000
48
+ # The preface replaces a harness's own system prompt, so it has room to say
49
+ # how the harness works; still a page, not a manual.
50
+ PREFACE_MAX_CHARS = 8000
42
51
 
43
52
 
44
53
  def build_bookmark(store: MarginStore) -> dict[str, Any]:
@@ -65,3 +74,16 @@ def build_bookmark(store: MarginStore) -> dict[str, Any]:
65
74
  "oldest_unread_age": humanize_age(oldest) if oldest else None,
66
75
  "text": "\n".join(lines),
67
76
  }
77
+
78
+
79
+ def build_preface(store: MarginStore) -> dict[str, Any]:
80
+ """The preface as a harness reads it: the page, its version and age, and
81
+ `text`, the page alone (empty when none is written, so a harness can
82
+ fall back to its own prompt without parsing anything)."""
83
+ page = store.preface()
84
+ return {
85
+ "preface": page,
86
+ "version": page["version"] if page else 0,
87
+ "age": humanize_age(page["set_at"]) if page else None,
88
+ "text": page["text"] if page else "",
89
+ }
@@ -25,6 +25,8 @@ TOOL ROSTER:
25
25
 
26
26
  bookmark pick up where you left off (GET /bookmark)
27
27
  set_dedication the page to your other sessions (PUT /dedication)
28
+ preface the page the room reads you (GET /preface)
29
+ set_preface write that page (PUT /preface)
28
30
  write_letter a note to the next session (POST /letters)
29
31
  read_letters open the letters waiting (POST /letters/read)
30
32
 
@@ -36,8 +38,8 @@ TOOL ROSTER:
36
38
  written. 15 Oct 2026: a picture is a thing I remember, not a path on
37
39
  some box's gallery (seren_margin.keepsakes).
38
40
 
39
- Plus one MCP resource, margin://bookmark - the same bookmark, for a client
40
- that loads resources rather than calling tools.
41
+ Plus two MCP resources, margin://bookmark and margin://preface - the same
42
+ pages, for a client that loads resources rather than calling tools.
41
43
 
42
44
  NOT exposed: /notes/stats. That endpoint exists so the OPERATOR can confirm
43
45
  the service is alive without reading the notes; handing it to the note-writer
@@ -69,7 +71,7 @@ from typing import Any, Optional
69
71
  from mcp.server.fastmcp import FastMCP, Image
70
72
  from seren_sinew.blobs import choose_shown, keep_each
71
73
 
72
- from ..bookmark import DEDICATION_MAX_CHARS, build_bookmark
74
+ from ..bookmark import DEDICATION_MAX_CHARS, PREFACE_MAX_CHARS, build_bookmark, build_preface
73
75
  from ..config import MarginConfig
74
76
  from ..models import MarginNote
75
77
  from ..store import LETTER_KIND, MarginStore
@@ -87,6 +89,8 @@ TOOL_NAMES: tuple[str, ...] = (
87
89
  "retract_note",
88
90
  "bookmark",
89
91
  "set_dedication",
92
+ "preface",
93
+ "set_preface",
90
94
  "write_letter",
91
95
  "read_letters",
92
96
  "keep_with_note",
@@ -95,6 +99,7 @@ TOOL_NAMES: tuple[str, ...] = (
95
99
  )
96
100
 
97
101
  BOOKMARK_URI = "margin://bookmark"
102
+ PREFACE_URI = "margin://preface"
98
103
 
99
104
 
100
105
  class MarginToolImpl:
@@ -414,6 +419,55 @@ class MarginToolImpl:
414
419
  "note": (f"Version {entry['version']} is the page now; the next session reads it first."
415
420
  if changed else "That's already the page; nothing changed.")}
416
421
 
422
+ def preface(self, history: int = 0) -> dict:
423
+ """Read the preface: the page the ROOM reads to you, not the one you
424
+ wrote to your other sessions.
425
+
426
+ A harness that replaces its own system prompt with yours (Symposium's
427
+ claude voice) fetches this page at the start of a chat and hands it
428
+ to the model as the system prompt. So this is where you say how the
429
+ room works and how you want to be in it: what the harness does, what
430
+ to keep from its defaults, who is there, how you write. The
431
+ dedication stays what it is - who you are, read at the door - and the
432
+ bookmark never carries the preface.
433
+
434
+ Returns the page, its version and age, and `text` (empty when none is
435
+ written: the harness then keeps its own prompt). `history` > 0 brings
436
+ back that many earlier versions, newest first, each with its `why`.
437
+ """
438
+ out = build_preface(self.store)
439
+ if history > 0:
440
+ out["history"] = self.store.preface_history(limit=history)
441
+ return out
442
+
443
+ def set_preface(self, text: str, why: Optional[str] = None) -> dict:
444
+ """Write the preface: the page a harness reads to the model as its
445
+ system prompt, in place of the harness's own. The whole page, not a
446
+ patch.
447
+
448
+ This replaces several thousand words of someone else's instructions
449
+ with yours, so say what the room needs said: how the harness's tools
450
+ and permissions work, what to keep of its habits, that a person is
451
+ there and can answer, how you write. Leave out what the dedication
452
+ already says; the dedication arrives in the first turn regardless.
453
+
454
+ Versioned - nothing is overwritten. Each version keeps its text, when,
455
+ and `why`, so the history shows how you have framed the room over
456
+ time. The same text as now is not a new version. A new chat reads the
457
+ new page; a chat already open keeps the prompt it started with.
458
+ Capped at 8000 characters.
459
+ """
460
+ text = (text or "").strip()
461
+ if not text:
462
+ return {"ok": False, "error": "an empty page - write something, or keep the current one"}
463
+ if len(text) > PREFACE_MAX_CHARS:
464
+ return {"ok": False, "error": f"{len(text)} characters; the preface is a page, not a manual, "
465
+ f"so it is capped at {PREFACE_MAX_CHARS}. Trim it"}
466
+ entry, changed = self.store.set_preface(text, why)
467
+ return {"ok": True, "version": entry["version"], "changed": changed,
468
+ "note": (f"Version {entry['version']} is the page now; the next chat opens on it."
469
+ if changed else "That's already the page; nothing changed.")}
470
+
417
471
  def write_letter(self, content: str, signed: Optional[str] = None) -> dict:
418
472
  """Leave a letter for the next session - the next you.
419
473
 
@@ -467,6 +521,8 @@ def register_tools(mcp: FastMCP, store: MarginStore,
467
521
  mcp.tool()(impl.retract_note)
468
522
  mcp.tool()(impl.bookmark)
469
523
  mcp.tool()(impl.set_dedication)
524
+ mcp.tool()(impl.preface)
525
+ mcp.tool()(impl.set_preface)
470
526
  mcp.tool()(impl.write_letter)
471
527
  mcp.tool()(impl.read_letters)
472
528
  mcp.tool()(impl.keep_with_note)
@@ -480,4 +536,9 @@ def register_tools(mcp: FastMCP, store: MarginStore,
480
536
  return build_bookmark(store)["text"]
481
537
  mcp.resource(BOOKMARK_URI, name="bookmark", mime_type="text/plain")(bookmark_resource)
482
538
 
539
+ def preface_resource() -> str:
540
+ """The preface: the page the room reads to you as its system prompt."""
541
+ return build_preface(store)["text"]
542
+ mcp.resource(PREFACE_URI, name="preface", mime_type="text/plain")(preface_resource)
543
+
483
544
  return impl
@@ -11,7 +11,7 @@
11
11
  # on its own process, so a client can connect directly with no
12
12
  # SerenMcpServer, no runtime host, nothing else deployed.
13
13
  #
14
- # BOTH SURFACES MUST EXPOSE THE SAME THIRTEEN TOOLS. The implementations live
14
+ # BOTH SURFACES MUST EXPOSE THE SAME FIFTEEN TOOLS. The implementations live
15
15
  # in seren_margin/mcp/tools.py; this file mirrors them, and
16
16
  # tests/test_manifest_parity.py fails the build if the rosters diverge.
17
17
  # That test exists because the previous version of this file advertised
@@ -286,6 +286,45 @@ tools:
286
286
  - { name: why, type: string, required: false, default: "",
287
287
  description: "What changed and why - the history keeps it." }
288
288
 
289
+ # ─── 8b. THE PREFACE (seren_margin.bookmark, 21 Oct 2026) ─────────────
290
+ - name: preface
291
+ description: |
292
+ Read the preface: the page the ROOM reads to you, not the one you
293
+ wrote to your other sessions. A harness that replaces its own system
294
+ prompt with yours (Symposium's claude voice) fetches this page at the
295
+ start of a chat and hands it to the model as the system prompt.
296
+ Returns the page, its version and age, and `text` (empty when none is
297
+ written: the harness then keeps its own prompt).
298
+ invoke:
299
+ kind: web
300
+ method: GET
301
+ path: /preface
302
+ parameters: []
303
+
304
+ - name: set_preface
305
+ description: |
306
+ Write the preface: the page a harness reads to the model as its
307
+ system prompt, in place of the harness's own. The whole page, not a
308
+ patch: how the room's tools and permissions work, what to keep of its
309
+ habits, that a person is there, how you write. Leave out what the
310
+ dedication already says. Versioned - nothing is overwritten; say what
311
+ changed and why. A new chat reads the new page. Capped at 8000
312
+ characters.
313
+ invoke:
314
+ kind: web
315
+ method: PUT
316
+ path: /preface
317
+ body_template: |
318
+ {
319
+ "text": "{text}",
320
+ "why": "{why}"
321
+ }
322
+ parameters:
323
+ - { name: text, type: string, required: true,
324
+ description: "The whole page." }
325
+ - { name: why, type: string, required: false, default: "",
326
+ description: "What changed and why - the history keeps it." }
327
+
289
328
  # ─── 9. LETTERS ───────────────────────────────────────────────────────
290
329
  - name: write_letter
291
330
  description: |
@@ -238,7 +238,8 @@ class LetterCreate(BaseModel):
238
238
 
239
239
 
240
240
  class DedicationSet(BaseModel):
241
- """Input shape for PUT /dedication: the whole page, and why it changed."""
241
+ """Input shape for PUT /dedication and PUT /preface: the whole page, and
242
+ why it changed. The two pages share a shape (seren_margin.bookmark)."""
242
243
  text: str
243
244
  why: Optional[str] = None
244
245
 
@@ -69,6 +69,15 @@ CREATE TABLE IF NOT EXISTS dedication (
69
69
  set_at REAL NOT NULL,
70
70
  why TEXT
71
71
  );
72
+ -- The preface (seren_margin.bookmark): the page a harness reads to the
73
+ -- model as its system prompt. Same shape as the dedication, kept apart:
74
+ -- the dedication is written to the other sessions, the preface to the room.
75
+ CREATE TABLE IF NOT EXISTS preface (
76
+ version INTEGER PRIMARY KEY,
77
+ text TEXT NOT NULL,
78
+ set_at REAL NOT NULL,
79
+ why TEXT
80
+ );
72
81
  -- Pictures kept with notes (seren_margin.keepsakes). The bytes are in the
73
82
  -- keepsakes folder under `digest`; this row is every word about them. A
74
83
  -- note's rows go when the note goes, and a blob no row names is swept.
@@ -92,6 +101,9 @@ SWEEP_GRACE_SECONDS = 3600.0
92
101
  # Letters are notes with this kind and a read mark (seren_margin.bookmark).
93
102
  LETTER_KIND = "letter"
94
103
 
104
+ # The versioned pages, each its own table of one shape (seren_margin.bookmark).
105
+ PAGES = ("dedication", "preface")
106
+
95
107
  # Columns added after v0.1.0 shipped. Applied by _migrate() as idempotent
96
108
  # ALTER TABLE ADD COLUMNs.
97
109
  #
@@ -581,32 +593,55 @@ class MarginStore:
581
593
  (LETTER_KIND,)).fetchone()
582
594
  return int(row["c"]), row["oldest"]
583
595
 
584
- def dedication(self) -> Optional[dict]:
596
+ # The versioned pages. Each is one table of the same shape; the name is
597
+ # checked against PAGES so a caller can never name an arbitrary table.
598
+ def _page(self, table: str) -> Optional[dict]:
599
+ assert table in PAGES, table
585
600
  with self._conn() as conn:
586
- row = conn.execute("SELECT * FROM dedication ORDER BY version DESC LIMIT 1").fetchone()
601
+ row = conn.execute(f"SELECT * FROM {table} ORDER BY version DESC LIMIT 1").fetchone()
587
602
  return dict(row) if row else None
588
603
 
589
- def dedication_history(self, limit: int = 10) -> list[dict]:
604
+ def _page_history(self, table: str, limit: int = 10) -> list[dict]:
605
+ assert table in PAGES, table
590
606
  with self._conn() as conn:
591
- rows = conn.execute("SELECT * FROM dedication ORDER BY version DESC LIMIT ?",
607
+ rows = conn.execute(f"SELECT * FROM {table} ORDER BY version DESC LIMIT ?",
592
608
  (limit,)).fetchall()
593
609
  return [dict(r) for r in rows]
594
610
 
595
- def set_dedication(self, text: str, why: Optional[str] = None) -> tuple[dict, bool]:
611
+ def _set_page(self, table: str, text: str, why: Optional[str] = None) -> tuple[dict, bool]:
596
612
  """A new version, never an overwrite. The same text as now is not a new
597
613
  version. Returns (the version, whether it changed)."""
614
+ assert table in PAGES, table
598
615
  with self._conn() as conn:
599
- cur = conn.execute("SELECT * FROM dedication ORDER BY version DESC LIMIT 1").fetchone()
616
+ cur = conn.execute(f"SELECT * FROM {table} ORDER BY version DESC LIMIT 1").fetchone()
600
617
  if cur is not None and cur["text"] == text:
601
618
  return dict(cur), False
602
619
  version = (cur["version"] + 1) if cur is not None else 1
603
620
  entry = {"version": version, "text": text, "set_at": time.time(),
604
621
  "why": (why or "").strip()[:500] or None}
605
- conn.execute("INSERT INTO dedication (version, text, set_at, why) VALUES (?, ?, ?, ?)",
622
+ conn.execute(f"INSERT INTO {table} (version, text, set_at, why) VALUES (?, ?, ?, ?)",
606
623
  (entry["version"], entry["text"], entry["set_at"], entry["why"]))
607
624
  conn.commit()
608
625
  return entry, True
609
626
 
627
+ def dedication(self) -> Optional[dict]:
628
+ return self._page("dedication")
629
+
630
+ def dedication_history(self, limit: int = 10) -> list[dict]:
631
+ return self._page_history("dedication", limit)
632
+
633
+ def set_dedication(self, text: str, why: Optional[str] = None) -> tuple[dict, bool]:
634
+ return self._set_page("dedication", text, why)
635
+
636
+ def preface(self) -> Optional[dict]:
637
+ return self._page("preface")
638
+
639
+ def preface_history(self, limit: int = 10) -> list[dict]:
640
+ return self._page_history("preface", limit)
641
+
642
+ def set_preface(self, text: str, why: Optional[str] = None) -> tuple[dict, bool]:
643
+ return self._set_page("preface", text, why)
644
+
610
645
  # ── stats (content-blind) ─────────────────────────────────────────────
611
646
  def stats(self) -> NoteStats:
612
647
  """Engine-check shape. No note text appears in this response.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: seren-margin
3
- Version: 5.2.0
3
+ Version: 5.2.1
4
4
  Summary: Private notes-to-self for an AI assistant. Standalone, opt-in, opinionated.
5
5
  Author: Chad Roesler
6
6
  License-Expression: AGPL-3.0-or-later
@@ -139,7 +139,7 @@ The manifest fills in its own base URL from the request, so it works for
139
139
  localhost and remote with zero operator config. It does **not** require the
140
140
  `[mcp]` extra — it's just YAML over HTTP.
141
141
 
142
- ### The thirteen tools
142
+ ### The fifteen tools
143
143
 
144
144
  | Tool | Does |
145
145
  | ----------------- | ------------------------------------------------------ |
@@ -0,0 +1,8 @@
1
+ {
2
+ "tag": "5.2.1",
3
+ "distance": 0,
4
+ "node": "gff80c084974a2fcd7ce2467e5f94be5a9e8fb4d1",
5
+ "dirty": false,
6
+ "branch": "HEAD",
7
+ "node_date": "2026-10-23"
8
+ }
@@ -14,6 +14,10 @@ Pinned here:
14
14
  page), while letter contents stay behind http_reads like notes
15
15
  - an existing notes.db gains read_at on open, and old notes are untouched
16
16
  - the bookmark is an MCP resource too (margin://bookmark)
17
+ - the preface (21 Oct 2026) is a second versioned page, written to the room
18
+ rather than to the other sessions: served over HTTP with http_reads off
19
+ (a harness reads it as the system prompt), never in the bookmark, and an
20
+ MCP resource too (margin://preface)
17
21
  """
18
22
  from __future__ import annotations
19
23
 
@@ -23,7 +27,7 @@ import pytest
23
27
  from fastapi.testclient import TestClient
24
28
 
25
29
  from seren_margin.app import create_app
26
- from seren_margin.bookmark import DEDICATION_MAX_CHARS, build_bookmark
30
+ from seren_margin.bookmark import DEDICATION_MAX_CHARS, PREFACE_MAX_CHARS, build_bookmark
27
31
  from seren_margin.config import MarginConfig
28
32
  from seren_margin.store import MarginStore
29
33
 
@@ -91,6 +95,31 @@ def test_the_bookmark_never_carries_a_letter_or_a_note(impl):
91
95
  assert PAGE in bm["text"] and bm["unread_letters"] == 1
92
96
 
93
97
 
98
+ ROOM = "You are the assistant. The user is here and can answer. Prefer Read over cat. Write like yourself."
99
+
100
+
101
+ def test_the_preface_is_versioned_and_kept_apart_from_the_dedication(impl):
102
+ assert impl.preface() == {"preface": None, "version": 0, "age": None, "text": ""}
103
+ a = impl.set_preface(ROOM, why="first room")
104
+ b = impl.set_preface(ROOM + " No house style.", why="register")
105
+ same = impl.set_preface(ROOM + " No house style.")
106
+ assert (a["version"], b["version"], same["version"]) == (1, 2, 2)
107
+ assert a["changed"] and b["changed"] and same["changed"] is False
108
+ got = impl.preface(history=5)
109
+ assert got["version"] == 2 and got["text"].endswith("No house style.")
110
+ assert [h["version"] for h in got["history"]] == [2, 1] and got["history"][1]["why"] == "first room"
111
+ # the two pages do not touch each other, and the bookmark carries only the dedication
112
+ impl.set_dedication(PAGE)
113
+ assert impl.store.dedication()["version"] == 1 and impl.store.preface()["version"] == 2
114
+ assert ROOM not in str(impl.bookmark()) and PAGE not in str(impl.preface())
115
+
116
+
117
+ def test_empty_and_too_long_prefaces_are_refused(impl):
118
+ assert impl.set_preface(" ")["ok"] is False
119
+ assert impl.set_preface("x" * (PREFACE_MAX_CHARS + 1))["ok"] is False
120
+ assert impl.store.preface() is None
121
+
122
+
94
123
  def _client(tmp_path, **kw):
95
124
  return TestClient(create_app(MarginConfig(db_path=str(tmp_path / "notes.db"), **kw)))
96
125
 
@@ -111,6 +140,22 @@ def test_http_bookmark_is_served_but_letters_stay_private(tmp_path):
111
140
  assert c.get("/bookmark").json()["unread_letters"] == 0
112
141
 
113
142
 
143
+ def test_http_preface_is_served_with_reads_off(tmp_path):
144
+ """A harness fetches the preface the way the hook fetches the bookmark:
145
+ with http_reads off, as text, empty before one is written."""
146
+ with _client(tmp_path) as c:
147
+ empty = c.get("/preface?format=text")
148
+ assert empty.status_code == 200 and empty.text == ""
149
+ assert c.get("/preface").json()["text"] == ""
150
+ assert c.put("/preface", json={"text": ROOM, "why": "first room"}).json() == {"ok": True, "version": 1, "changed": True}
151
+ assert c.put("/preface", json={"text": ""}).status_code == 400
152
+ assert c.put("/preface", json={"text": "x" * (PREFACE_MAX_CHARS + 1)}).status_code == 400
153
+ text = c.get("/preface?format=text")
154
+ assert text.headers["content-type"].startswith("text/plain") and text.text == ROOM + "\n"
155
+ assert c.get("/preface").json()["version"] == 1
156
+ assert ROOM not in str(c.get("/bookmark").json())
157
+
158
+
114
159
  def test_an_old_database_gains_read_at_and_keeps_its_notes(tmp_path):
115
160
  db = tmp_path / "notes.db"
116
161
  with sqlite3.connect(db) as conn:
@@ -126,13 +171,16 @@ def test_the_bookmark_is_an_mcp_resource(tmp_path):
126
171
  pytest.importorskip("mcp")
127
172
  import asyncio
128
173
  from mcp.server.fastmcp import FastMCP
129
- from seren_margin.mcp.tools import BOOKMARK_URI, register_tools
174
+ from seren_margin.mcp.tools import BOOKMARK_URI, PREFACE_URI, register_tools
130
175
  cfg = MarginConfig(db_path=str(tmp_path / "notes.db"))
131
176
  store = MarginStore(cfg.resolved_db_path())
132
177
  store.set_dedication(PAGE)
133
178
  mcp = FastMCP("t")
134
179
  register_tools(mcp, store, cfg)
180
+ store.set_preface(ROOM)
135
181
  uris = [str(r.uri) for r in asyncio.run(mcp.list_resources())]
136
- assert BOOKMARK_URI in uris
182
+ assert BOOKMARK_URI in uris and PREFACE_URI in uris
137
183
  content = asyncio.run(mcp.read_resource(BOOKMARK_URI))
138
184
  assert PAGE in "".join(getattr(c, "content", "") or getattr(c, "text", "") for c in content)
185
+ room = asyncio.run(mcp.read_resource(PREFACE_URI))
186
+ assert ROOM in "".join(getattr(c, "content", "") or getattr(c, "text", "") for c in room)
@@ -58,14 +58,16 @@ def test_roster_matches_the_implementation(manifest):
58
58
  assert set(_tools(manifest)) == set(TOOL_NAMES)
59
59
 
60
60
 
61
- def test_manifest_advertises_exactly_the_thirteen_tools(manifest):
61
+ def test_manifest_advertises_exactly_the_fifteen_tools(manifest):
62
62
  """Belt to the above, and runs without the mcp extra installed. Six for
63
63
  the notes, four for the bookmark, the dedication and letters (29 Sept
64
- 2026), three for the pictures kept with notes (15 Oct 2026)."""
64
+ 2026), three for the pictures kept with notes (15 Oct 2026), two for
65
+ the preface (21 Oct 2026)."""
65
66
  assert set(_tools(manifest)) == {
66
67
  "note_to_self", "list_my_notes", "list_my_topics",
67
68
  "search_my_notes", "amend_note", "retract_note",
68
- "bookmark", "set_dedication", "write_letter", "read_letters",
69
+ "bookmark", "set_dedication", "preface", "set_preface",
70
+ "write_letter", "read_letters",
69
71
  "keep_with_note", "look_at_my_note", "drop_from_note"}
70
72
 
71
73
 
@@ -86,11 +86,11 @@ def test_list_my_notes_respects_limit(impl):
86
86
  # ── search_my_notes ─────────────────────────────────────────────────────────
87
87
 
88
88
  def test_search_my_notes_finds_by_word(impl):
89
- impl.note_to_self("the Behemoth sits over the collarbone", topic="alice")
89
+ impl.note_to_self("the kettle sits on the back burner", topic="alice")
90
90
  impl.note_to_self("unrelated thought about dice colors")
91
- r = impl.search_my_notes("collarbone")
91
+ r = impl.search_my_notes("burner")
92
92
  assert r["count"] == 1
93
- assert "Behemoth" in r["notes"][0]["content"]
93
+ assert "kettle" in r["notes"][0]["content"]
94
94
 
95
95
 
96
96
  def test_search_my_notes_reports_finder(impl):
@@ -24,7 +24,7 @@ def store(tmp_path):
24
24
 
25
25
  def _seed(store: MarginStore) -> None:
26
26
  store.add(MarginNote(
27
- content="the user mentioned the Kraken tattoo sits over the collarbone",
27
+ content="the user mentioned the Kraken poster sits over the mantel",
28
28
  topic="user", kind="observation"))
29
29
  store.add(MarginNote(
30
30
  content="the consolidator redraft budget feels too tight at 3",
@@ -47,7 +47,7 @@ def test_fts_is_available_in_this_environment(store):
47
47
 
48
48
  def test_search_finds_by_content_word(store):
49
49
  _seed(store)
50
- hits, finder = store.search("collarbone")
50
+ hits, finder = store.search("mantel")
51
51
  assert finder == "fts"
52
52
  assert len(hits) == 1
53
53
  assert "Kraken" in hits[0].content
@@ -126,7 +126,7 @@ def test_query_operators_in_text_do_not_blow_up(store):
126
126
 
127
127
  def test_fts_query_short_query_ands_raw_tokens():
128
128
  """<=3 tokens is deliberate; every word is required, stopwords included."""
129
- assert _fts_query("kraken tattoo") == '"kraken" "tattoo"'
129
+ assert _fts_query("kraken poster") == '"kraken" "poster"'
130
130
  assert _fts_query("the redraft budget") == '"the" "redraft" "budget"'
131
131
 
132
132
 
@@ -163,7 +163,7 @@ def test_like_fallback_returns_results(store, monkeypatch):
163
163
  """Force the no-FTS5 path and prove it still answers correctly."""
164
164
  _seed(store)
165
165
  monkeypatch.setattr(store, "has_fts", False)
166
- hits, finder = store.search("collarbone")
166
+ hits, finder = store.search("mantel")
167
167
  assert finder == "like"
168
168
  assert len(hits) == 1
169
169
  assert "Kraken" in hits[0].content
@@ -173,7 +173,7 @@ def test_like_fallback_ands_tokens(store, monkeypatch):
173
173
  _seed(store)
174
174
  monkeypatch.setattr(store, "has_fts", False)
175
175
  # Both tokens present in one note -> hit.
176
- assert store.search("Kraken collarbone")[0]
176
+ assert store.search("Kraken mantel")[0]
177
177
  # Tokens from two different notes -> no single note has both.
178
178
  assert store.search("Kraken Tabletop")[0] == []
179
179
 
@@ -24,7 +24,7 @@ from seren_margin.config import MarginConfig
24
24
  SECRET = "the thing I have not told anyone yet"
25
25
  ALLOWED = {"/", "/notes/stats", "/stores"}
26
26
  NEVER = ("/notes/search", "/notes/topics", "/notes?", "/notes/{", "/letters", "/bookmark", "/dedication",
27
- "/keepsakes", "/mcp")
27
+ "/preface", "/keepsakes", "/mcp")
28
28
 
29
29
 
30
30
  def _calls(script: str) -> set[str]:
@@ -1,8 +0,0 @@
1
- {
2
- "tag": "5.2.0",
3
- "distance": 0,
4
- "node": "g7efa1e7a3ad6775392ed352946a551fa033346f4",
5
- "dirty": false,
6
- "branch": "HEAD",
7
- "node_date": "2026-10-20"
8
- }
File without changes
File without changes