davepoon/read

/read

Surface a page's identity so the user can decide whether to open it. /read is preview, not full text. The body is on disk; preview keeps chat scannable, dodges Bash output truncation, and respects the "md is canonical, viewer is the user's editor" model.

How to invoke

Two shapes accepted:

1. Page id (starts with page_; legacy concept_ ids still work) → direct fetch.
2. Title or freeform word → search, pick best match, fetch.

Both end with the same preview block.

1. Direct id

Call the MCP tool to fetch the page:

get_page(page_id="<id>")

The response is a JSON object wrapping { "page": {...} }. Read title, summary, space, and source_memory_ids off the page, then look up the md filename in ~/.origin/pages/.origin/state.json:

Bash: python3 -c '
import json, os, sys
state_path = os.path.expanduser("~/.origin/pages/.origin/state.json")
pid = "<id>"
filename = None
try:
    with open(state_path) as f:
        filename = json.load(f).get("pages", {}).get(pid, {}).get("file")
except FileNotFoundError:
    pass
print(f"~/.origin/pages/{filename}" if filename else "(no md projection on disk)")
'

Combine the page fields with the resolved md path and emit the preview block.

2. Title or freeform word

Search first, then fetch the top hit by id and run the same preview block. Always resolve through the search_pages MCP tool — never derive a slug client-side (skill heuristics drift from the canonical slugify() on apostrophes and punctuation).

search_pages(query="<arg>", limit=1)

Parse the returned JSON — the response shape is { "pages": [...] }. Read the first hit's id. If pages is empty, tell the user "no page found matching <arg> — try /distill <arg> to create one" and stop. Otherwise call get_page(page_id=<id>) and emit the same preview block from section 1.

Output shape

Always print exactly these lines (no body):

Title:    <title>
Version:  v<N> — <last_edited_by> <relative_time> (<last_delta_summary>)
Summary:  <one sentence>
Sources:  <N> memories
Space:    <space or (none)>
Links:    <N inbound, M outbound (<K> broken)>
Open:     ~/.origin/pages/<slug>.md
⚠ Stale: <stale_reason> — run /distill to refresh

Lock banner rule:

When the page payload returned by get_page has user_edited == true, prepend this line as the very first line of the rendered output, before the title:

🔒 You've edited this page. Auto-refresh paused. `/distill rebuild <page-id>` to unlock.

Substitute <page-id> with the actual page.id value. When user_edited is false or absent, omit this line entirely.

The lock means daemon distill cycles will not auto-rewrite this page's prose from sources — edits stay until the user explicitly runs /distill rebuild to wipe and regenerate.

Version line rules:

• Always show v<N>. When version is null or missing, omit the line.
• Append — <last_edited_by> when populated (e.g. re_distill, user, agent).
• Append relative time when last_edited_at is set (e.g. 2h ago, 3d ago).
• Append (<last_delta_summary>) when the field is non-empty.
• Examples:
  • v1 — synthesized 4h ago
  • v4 — re_distill 2h ago (+mem_xyz, +250 chars)
  • v3 — user 1d ago

Stale warning rule:

• Emit the ⚠ Stale: line only when stale_reason is non-null/non-empty.
• Render stale_reason verbatim (daemon sets it; values like source_updated, new_memories are human-readable enough).

Links line rules (unchanged): Call get_page_links(page_id="<id>") right after get_page and count:

• inbound = len(inbound)
• outbound = len(outbound)
• broken = outbound entries where target_page_id is null

Omit the parenthetical when broken is zero. Drop the line entirely if inbound + outbound is zero.

Don't paraphrase the title, don't trim the summary, don't decorate the preview. The block is one screen, predictable, easy to skim.

If the user wants the full body, they open the md file in their editor (Obsidian, VS Code, glow, bat, …). The plugin doesn't render markdown better than their tools do.

When to use

• User asks "show me the page on X", "what's in <title>", "preview that".
• After /distill finishes, follow up with /read "<title>" (titles survive any rendering surface; ids may visually truncate).

When NOT to use

• Raw memory lookups → use /recall.
• Listing all pages → list_pages_recent MCP tool or ls ~/.origin/pages/.
• Reading the full body → open the md file in the user's editor.