# Links

> Write any link or URL so it resolves where it is rendered, not where it lives in the repo. Use when authoring or editing a link — in docs/wg specs, crate READMEs and docstrings, the npm-published wasm package README, or skills. This is the engine-repo variant of the grida links doctrine.

- Skill: `gridaco/links` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gridaco/links`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gridaco/links/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gridaco (https://skillmd.com/u/gridaco)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gridaco/links

---


# Links (engine repo)

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. Before you write
any link: (1) where is this text rendered? (2) who reads it there? (3) when
they click, where does it resolve *from that host* — and is that the thing
you meant?

## Surfaces in this repo

| Surface                | Lives in                                    | Audience         |
| ---------------------- | ------------------------------------------- | ---------------- |
| GitHub (repo browse)   | everything — incl. `docs/wg/**` (also published by this repo's `www/` docs app, which resolves the same `.md`-suffixed relative links; GitHub remains the canonical host) | engine developers |
| npm (`npmjs.com`)      | `crates/grida-canvas-wasm` package README   | package users    |
| Raw / no host          | IDE, stack traces, compiled output          | whoever has it   |

## First-party hosts

| URL                                  | What                                                                                            |
| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `https://github.com/gridaco/nothing` | **This repo.** File → `…/blob/main/<path>`; dir → `…/tree/main/<path>`; `main` only, never a SHA |
| `https://github.com/gridaco/grida`   | The product monorepo (editor, packages, service docs). Same file/dir forms                       |
| `https://grida.co`                   | The product · `https://grida.co/docs` = the product docs site (publishes **grida's** docs tree)  |

## Decision table

| Rendered in                       | Target                                   | Use                                                       |
| --------------------------------- | ---------------------------------------- | --------------------------------------------------------- |
| anywhere in this repo             | anything in this repo (crates, docs/wg, fixtures, format) | **relative repo path** — same host (GitHub) everywhere |
| anywhere in this repo             | a grida-repo file/dir                    | **absolute** `https://github.com/gridaco/grida/blob|tree/main/<path>` |
| anywhere in this repo             | a published grida docs page (staying clusters: platform, ai, …) | hosted URL `https://grida.co/docs/<path>` |
| npm package README                | anything in-repo                         | **absolute** `https://github.com/gridaco/nothing/blob/main/<path>` — relative dies on npmjs.com |
| any                               | external                                 | `https://…` as-is                                         |

## Hard rules

- **Never author `https://grida.co/docs/wg/<engine-cluster>/…` links.** The
  docs site does not publish this repo's wg tree (canvas, format, research,
  engine feat-*). Old published URLs survive via a redirect shim in grida —
  do not author *new* links through a redirect; use the same-repo relative
  path (in-repo surfaces) or this repo's absolute GitHub URL (external
  surfaces).
- **Cross-repo links are always absolute.** A relative path can never reach
  the other repo.
- **`main` only** — never pin a commit/branch SHA.
- **Cross-host `#fragment`:** link the file, not a guessed anchor, unless
  verified in the target host's slug scheme.
- **No local-only references — clean them before commit**: absolute machine
  paths (`/Users/...`), `/tmp`, untracked or gitignored files
  (`fixtures/local/**` may be *described* as local-only, never linked as if
  it resolves). If `git ls-files` doesn't show it and it isn't a public URL,
  it does not exist for the audience.