# Trail URLs — the shared reading-context format

A trail URL serializes a reading context: an ordered path of panes,
root → focus, exactly as the Reading Room lays it out on screen. It is the
context object humans and agents exchange (ADR 0005 decision 14): an agent
mints a trail to hand a human its reasoning chain, reconstructed pane by
pane; an agent parses a human's trail to load what they were reading. The
format is stable and constructible — nothing in it requires the room.

The canonical copy of this document is published in-universe; the repository
copy at `docs/trail-format.md` (repo `latebit-io/demarkus-library`) is its
source. The companion style document is the
[authoring contract](/.well-known/library/authoring.md).

## Format

```
/t/<pane>/~/<pane>/~/<pane>?focus=<i>
```

- **Pane chunk** — the tail of the pane's standalone `/w/` route:
  - document: `<world>/d/<path>` — e.g. `soul.demarkus.io/d/adr/0005.md`
  - listing: `<world>/d/<dir>/` (trailing slash) — e.g. `root/d/plans/`
  - graph: `<world>/g/<path>` — the document's graph neighborhood (its links
    and backlinks) as a pane, e.g. `root/g/adr/0005.md`. Same value rule as a
    document; clicking a node continues the trail.
  - tag page: `<world>/tags/<tag>` — e.g. `root/tags/architecture`
  - the floor: the single segment `u` — the universe view (pane zero), no
    world part because the floor IS the whole universe. `/` redirects to
    `/t/u`.
  - world map: `<world>/u/` (trailing slash, no value) — the floor zoomed into
    one world: its catalog as directory clusters, e.g. `root/u/`. The same `u`
    kind as the floor, distinguished by the world part; clicking a world on the
    floor opens its map, a directory's aggregate opens that listing.
- **`~`** — the reserved separator: a path segment that is exactly `~`
  between consecutive pane chunks.
- **`focus`** — 0-based index of the focused pane (full render + margin +
  live fetch). Omitted ⇒ the last pane. Out of range ⇒ clamped.
- **Worlds** are knowledge-system names (`root`) or demarkus hosts
  (`soul.demarkus.io`, `wiki.example.org:6310`). Paths keep raw slashes —
  no percent-encoded `/`.
- **Depth cap: 10 panes.** URLs with more are rejected (400). When a click
  would push past the cap, the room drops the oldest pane.

Example — the floor, a tag page, and a document, attention on the tag page:

```
/t/u/~/root/tags/adr/~/root/d/adr/0005.md?focus=1
```

## Semantics (what the room guarantees)

- The trail is a single reasoning path, not a browsing history. A link
  clicked in pane N discards panes right of N and appends the target,
  focusing it. A target already on the path is focused, never duplicated.
- The whole canvas renders from the URL alone — server state, no client
  state. Sharing the URL shares the exact reconstruction.
- Every link the room renders already carries its post-click trail URL, so
  fetching a trail page and following hrefs is itself a valid way for an
  agent to walk the space of next states.
- The floor pane renders the same data an agent reads via `mark_worlds`
  plus per-world `mark_lookup` with the match-all query `*` (importance
  order) — the projection adds layout, never information. A world map
  (`<world>/u/`) is the same data for one world, grouped by directory.
- The graph pane (`g`) renders one document with its observed links and
  backlinks; each node is a link that continues the trail. Its edges come
  from the room's render-time observed-links map, so a neighborhood is
  sparse until the connected documents have been read — an honest cold
  state, not a gap.

## Minting (agent → human)

Concatenate route tails with `/~/`, set `focus` if not last. Rules:

- ≤ 10 panes; each pane's world+path must read (an unreadable unfocused
  pane renders as a tombstone, the trail survives; an unreadable focused
  pane is the page's error).
- Order IS the argument: pane 0 is where the reasoning starts, focus is
  where you want the reader's attention to land. Starting at `u` hands the
  reader the map before the path.
- Don't percent-encode slashes; do percent-encode characters that are not
  valid in a URL path segment.

## Parsing (human → agent)

Split the path after `/t/` on `/~/`; each chunk is `<world>/<kind>/<value>`
(kind `d` ⇒ document path `/<value>`, kind `g` ⇒ that document's graph
neighborhood, kind `u` with a world ⇒ that world's map, kind `tags` ⇒ tag
page) or the bare `u` floor chunk. Read the documents over mark://
(`mark://<world>/<path>`) in order — that ordered list, plus the focus index,
is the reader's current context.