Cross-project links

A project's identity is the URL of its git repository — decentralised, no registry. GitHub is the common host, but any git remote is equal.

Registration

A space registers each project it knows under a short alias:

https://github.com/you/proj = proj

Connecting a project to a space means adding this line; opening one that is not on the machine yet means cloning that URL.

Links

The primary form is the alias:

See [the first document](@proj/docs/doc1.md).

@proj/docs/doc1.md resolves through the space's registration to the local clone. The alias is stable across machines because the registration travels with the space, not with the machine.

A direct URL is the secondary form: an ordinary https://github.com/you/proj/blob/main/docs/doc1.md link is recognised by its registered remote and opened locally when the project is connected — and it still works as a plain web link everywhere else.

Rules

1. An @alias nobody registered is not a link — the text is left as written and drawn as text.
2. Renaming an alias rewrites @alias/ links in the space's own documents in the same operation; it never edits a connected project's files.
3. A link into a project that is registered but not downloaded offers to fetch it, in plain language.