links

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)

| Surface | Lives in | Audience | | --------------------------------------- | ----------------------------------------- | -------------------- | | Docs site (Docusaurus, grida.co/docs) | docs/** | users / contributors | | GitHub (repo browse) | source files, repo-root *.md | developers | | npm (npmjs.com) | published packages/*/README.md | package users | | Product UI (grida.co app) | editor/app/** strings/components | product users | | Raw / no host | IDE, stack trace, pasted, compiled output | whoever has it |

Decision table (rendered host → target → form)

| Rendered in | Target | Use | | ------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Docs site | another docs page | relative within /docs | | Docs site | repo path outside /docs | absolute GitHub URL | | Docs site / Product UI | the product / dashboard / editor | universal route | | Source code | a docs page | hosted docs URL | | Source code | another source file | relative repo path | | npm README | anything in-repo | absolute (GitHub URL or grida.co) | | Product UI | a docs page | hosted docs URL (or universal route) | | Repo-root *.md (GitHub) | docs / source | relative works on GitHub but lands on raw .md; use the hosted docs URL when you mean the rendered doc | | Any | external | https://… as-is |

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.

| URL | What | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | https://grida.co | Main website (marketing / product root) | | https://grida.co/docs | Docs site (Docusaurus). docs/<path>.md → https://grida.co/docs/<path> (drop the docs/ prefix and the extension) | | https://grida.co/_/<path> | Universal route — resolves to the tenant path /:org/:project/... at runtime | | https://github.com/gridaco | The GitHub org | | https://github.com/gridaco/grida | This repo. File → …/gridaco/grida/blob/main/<path>; dir → …/gridaco/grida/tree/main/<path> |

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. Use the absolute GitHub URL. (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.