docs: expand user guides

packages/docs/references.mdx

@@ -0,0 +1,177 @@
+---
+title: "References"
+description: "Make local directories and Git repositories available as project context."
+---
+
+References give OpenCode named access to directories outside the current
+project. Use them for documentation, shared libraries, examples, or source from
+another repository.
+
+Configure references by alias in `opencode.json` or `opencode.jsonc`:
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "references": {
+    "docs": {
+      "path": "../product-docs",
+      "description": "Use for product behavior and terminology"
+    },
+    "effect": {
+      "repository": "Effect-TS/effect",
+      "branch": "main",
+      "description": "Use for Effect implementation details"
+    }
+  }
+}
+```
+
+## Local directories
+
+Use `path` for a local directory:
+
+```jsonc
+{
+  "references": {
+    "design-system": {
+      "path": "../design-system",
+      "description": "Use when working with components or design tokens"
+    }
+  }
+}
+```
+
+Relative paths resolve from the directory containing the config file that
+defines them. Absolute paths and home-relative paths such as `~/docs` are also
+supported.
+
+The string shorthand is useful when no other fields are needed:
+
+```jsonc
+{
+  "references": {
+    "docs": "../docs",
+    "shared": "~/work/shared"
+  }
+}
+```
+
+<Note>
+  A shorthand string is treated as a local path only when it starts with `.`,
+  `/`, or `~`. Use `./docs`, not `docs`; a bare `docs` value is interpreted as
+  a Git repository.
+</Note>
+
+## Git repositories
+
+Use `repository` for a remote Git repository. GitHub `owner/repo` shorthand,
+Git URLs, host/path forms, and SCP-style remotes are supported.
+
+```jsonc
+{
+  "references": {
+    "effect": {
+      "repository": "Effect-TS/effect",
+      "branch": "main"
+    },
+    "internal-sdk": {
+      "repository": "git@gitlab.example.com:platform/sdk.git",
+      "branch": "release/v2"
+    }
+  }
+}
+```
+
+Without `branch`, OpenCode checks out and refreshes the remote's default
+branch. Branch names may contain letters, numbers, `/`, `_`, `.`, and `-`, but
+cannot start with `-` or contain `..`. Local `file:` repositories are not
+supported.
+
+Git references also support shorthand:
+
+```jsonc
+{
+  "references": {
+    "effect": "Effect-TS/effect",
+    "sdk": "gitlab.com/platform/sdk"
+  }
+}
+```
+
+### Cloning and storage
+
+OpenCode normalizes a remote and stores one checkout under its global data
+directory at `opencode/repos/<host>/<repository-path>`. On a typical Linux
+installation, for example, `Effect-TS/effect` is stored at:
+
+```text
+~/.local/share/opencode/repos/github.com/Effect-TS/effect
+```
+
+Missing repositories are cloned. Existing checkouts are fetched and reset to
+the requested branch, or to the remote default branch when `branch` is omitted.
+Materialization runs asynchronously when references load or reload, so a new
+reference can appear before its checkout is ready. Clone and refresh failures
+are logged and do not stop other references from loading.
+
+<Warning>
+  The cache has one checkout per normalized remote, not one per branch. Do not
+  configure the same repository at multiple branches; only one branch can be
+  exposed. Avoid editing cached checkouts because a refresh resets them.
+</Warning>
+
+## Description and visibility
+
+`description` tells agents when a reference is relevant. References with a
+description are included in agent instructions with their alias and resolved
+path. References without one remain available in `@` autocomplete but are not
+advertised automatically.
+
+Set `hidden` to `true` to remove a reference from TUI `@` autocomplete:
+
+```jsonc
+{
+  "references": {
+    "internal": {
+      "path": "../internal",
+      "description": "Use for internal service behavior",
+      "hidden": true
+    }
+  }
+}
+```
+
+`hidden` controls only autocomplete visibility. It does not remove the
+reference from the reference API or agent instructions when a description is
+present.
+
+## Use references
+
+Type `@` in the TUI and select a reference alias to attach its root directory:
+
+```text
+Compare the current implementation with @effect
+```
+
+The attachment provides a non-recursive listing of the root's immediate files
+and directories. V2 currently attaches references by root alias;
+`@alias/path` is not a reference-specific file browser. Ask the agent to
+inspect a particular path when more detail is needed.
+
+References do not grant extra tool permissions. Access outside the active
+Location remains subject to the agent's normal tool rules and the
+`external_directory` permission. Editing a reference additionally requires the
+applicable edit permission.
+
+## Fields
+
+| Field | Local | Git | Description |
+| --- | --- | --- | --- |
+| `path` | Required | No | Local directory path |
+| `repository` | No | Required | Remote Git repository |
+| `branch` | No | Optional | Branch to fetch and check out |
+| `description` | Optional | Optional | Guidance describing when agents should use it |
+| `hidden` | Optional | Optional | Hide it from TUI `@` autocomplete |
+
+An alias cannot be empty or contain `/`, `\`, whitespace, a backtick, or a
+comma.