Links

A link is correct or broken at the surface it is rendered on, for that surface's audience — not where the text lives in the repo. The same path string is valid in one host and dead in another. This skill is the single source of truth for which form to use; docs/AGENTS.md defers here.

Before you write any link, answer three questions

1. Where is this text rendered/hosted? (the surface)
2. Who is the audience there?
3. When they click, where does it resolve from that host — and is that the thing you meant?

Question 3 is the one that must not break. Everything below is just the answer table.

Surfaces (where text is rendered)

Decision table (rendered host → target → form)

Grida URLs

The only first-party hosts. Build every absolute link from these — if a link should be first-party but isn't one of these, it is wrong.

Decision row for engine targets: any grida surface → an engine-repo path → absolute https://github.com/gridaco/nothing/blob|tree/main/<path>. Never relative (different repo), never grida.co/docs/wg/<engine-cluster>/… — the docs site no longer publishes the engine wg clusters (canvas, format, research, feat-2d/svg/css/paragraph/text-editing/…). A redirect shim keeps old published URLs alive; do not author new links through a redirect.

The forms (exact)

Universal route — any "open this in the product" link. https://grida.co/_/<path> (e.g. /_/dash, /_/connect/share). A stable shorthand resolved at runtime to the tenant path /:org/:project/.... Never hardcode /:org/:project/.... Defined in docs/wg/platform/universal-docs-routing.md; register new user-facing pages there so the /_/ alias resolves.

Hosted docs URL — source code / product UI / npm → a docs page. https://grida.co/docs/<path> where <path> drops the docs/ prefix and the extension: docs/wg/platform/billing/ai-credits.md → https://grida.co/docs/wg/platform/billing/ai-credits. Not a relative ../../docs/.... Why: it points at the canonical rendered doc and survives file moves, paste, and stack traces. (New convention — existing source uses relative links; migrate opportunistically, do not churn.)

Absolute GitHub URL — docs site / npm → a repo path outside the deployable root. File: https://github.com/gridaco/grida/blob/main/<path>. Directory: https://github.com/gridaco/grida/tree/main/<path>. Always main; never pin a commit or other branch SHA — the reader must land on current main. (A file URL requires /blob/main/; there is no shorter valid form.)

Relative — only within the same host. Docs→docs relative within /docs; source→source relative repo path. Correct precisely because it resolves in that host.

Hard rules

• Never link outside /docs from a docs page with a relative path. Only /docs/** is deployed; ../../crates/... 404s on the site — and crates/ now lives in gridaco/nothing, so such a link is wrong twice. Use the absolute GitHub URL of the owning repo. (Supersedes any older "use inline code" guidance.)
• npm-published package READMEs (packages/* with "private": false): every in-repo reference must be absolute — relative paths die on npmjs.com.
• Cross-host #fragment: GitHub and Docusaurus slugify headings differently. When the link crosses render hosts, link the page/file, not a guessed anchor. Use a fragment only if you can verify it in the target host's slug scheme.
• Do not link from shipped docs to a draft: true, unpublished, or unlisted page — the target will not resolve on the site.
• Never target generated or synced trees (apps/docs/docs/**, docs/@designto-code/**). Link the docs/** source or its hosted URL.
• Source-code docstrings → docs: use the hosted docs URL. A relative ../../docs/... resolves on GitHub but lands on raw markdown and rots when the file moves.
• No local-only references — clean them before commit. While working you will reference things that exist only on your machine: absolute machine paths (/Users/..., ~/...), /tmp and scratch dirs, untracked or gitignored files, prior local research, ~/.claude/plans/.... They resolve to nothing for anyone else and leak into docstrings, docs, comments, and PR text far more often than you'd expect. Before commit, delete them or replace with a committed path / public URL. Verify: if git ls-files / git check-ignore shows the target isn't tracked and it isn't a public URL, it does not exist for the audience. This is correctness, not hygiene.

The pass (apply to every link you write or touch)

1. Name the render host (where this text is shown).
2. Name the target's canonical host.
3. Same host → relative is fine. Crossing hosts → use the target's canonical absolute form: grida.co/docs/... (a doc), grida.co/_/... (the product), or github.com/gridaco/grida/blob/main/... (a repo file).
4. No commit/branch SHA pins — main only.
5. No cross-host fragment guesses.
6. Target is actually published (not draft/unlisted, not a generated/synced copy).
7. Pre-commit gate: no local-only/untracked target — the referent exists for the audience, not just on your machine.