read

What this skill does

# /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.