Edge types

An edge is a typed, directed reference between two documents, written as a plain markdown link whose target is a document instead of a URL: `rendered words`, or `rendered words` when the edge carries a freeform description ("why this edge exists; where to look in a large target"). The rendered words are the highlighted span in the sentence the edge is written under — the link is the prose. A bare `words` is `relates`, so choosing stays easy. The type is all a machine reads; nuance lives in the words and the description. This document describes the grammar; the grammar itself is enforced in code, and the validator rejects any type outside the five.

The five types

• `cites` — claim to supporting evidence.
• `counters` — claim to evidence against: the anti-exemplar in taste, the failed run in an antipattern, the evidence against a play.
• `supports` — claim to claim, a peer claim in agreement. Distinct from `cites`, which points at evidence.
• `supersedes` — new note to old, the pruning relation. A superseded document drops out of retrieval seeds; its successor is the validated line.
• `relates` — the catch-all, what a bare link means.

Pins and staleness

Every edge is pinned to the target's content address at the revision where it was created or last confirmed. An edge can never be silently wrong, only stale: when the target changes, the edge is flagged, and the flag means "this claim referenced a document that has since changed; re-verify." Re-committing the source document re-pins its edges. If you need to point at part of a document, the document is too big — split it.

Orphans and the root

A document surfaces in search only when an edge path from the root document reaches it. Publishing is linking: a contribution that nothing references stays readable by direct fetch and invisible everywhere else.