feat(core): add project reference guidance (#31601)

packages/core/src/config/plugin/reference.ts

@@ -33,11 +33,15 @@ export const Plugin = {
                 path: AbsolutePath.make(
                   localPath(directory, global.home, typeof entry === "string" ? entry : entry.path),
                 ),
+                description: typeof entry === "string" ? undefined : entry.description,
+                hidden: typeof entry === "string" ? undefined : entry.hidden,
               })
             : new Reference.GitSource({
                 type: "git",
                 repository: typeof entry === "string" ? entry : entry.repository,
                 branch: typeof entry === "string" ? undefined : entry.branch,
+                description: typeof entry === "string" ? undefined : entry.description,
+                hidden: typeof entry === "string" ? undefined : entry.hidden,
               }),
         )
       }

packages/core/src/config/reference.ts

@@ -5,10 +5,14 @@ import { Schema } from "effect"
 export class Git extends Schema.Class<Git>("ConfigV2.Reference.Git")({
   repository: Schema.String,
   branch: Schema.String.pipe(Schema.optional),
+  description: Schema.String.pipe(Schema.optional),
+  hidden: Schema.Boolean.pipe(Schema.optional),
 }) {}
 
 export class Local extends Schema.Class<Local>("ConfigV2.Reference.Local")({
   path: Schema.String,
+  description: Schema.String.pipe(Schema.optional),
+  hidden: Schema.Boolean.pipe(Schema.optional),
 }) {}
 
 export const Entry = Schema.Union([Schema.String, Git, Local])

packages/core/src/location-layer.ts

@@ -1,4 +1,4 @@
-import { Layer, LayerMap } from "effect"
+import { Effect, Layer, LayerMap } from "effect"
 import { Location } from "./location"
 import { Policy } from "./policy"
 import { Config } from "./config"
@@ -23,6 +23,7 @@ import { Watcher } from "./filesystem/watcher"
 import { LocationMutation } from "./location-mutation"
 import { FileMutation } from "./file-mutation"
 import { Reference } from "./reference"
+import { ReferenceGuidance } from "./reference/guidance"
 import { RepositoryCache } from "./repository-cache"
 import { Pty } from "./pty"
 import { SkillV2 } from "./skill"
@@ -45,6 +46,9 @@ import { FetchHttpClient } from "effect/unstable/http"
 
 export class LocationServiceMap extends LayerMap.Service<LocationServiceMap>()("@opencode/example/LocationServiceMap", {
   lookup: (ref: Location.Ref) => {
+    const boot = Layer.effectDiscard(
+      Effect.logInfo("booting location services", { directory: ref.directory, workspaceID: ref.workspaceID }),
+    )
     const location = Location.layer(ref)
     const systemContext = SystemContextBuiltIns.locationLayer
     const base = Layer.mergeAll(
@@ -74,6 +78,7 @@ export class LocationServiceMap extends LayerMap.Service<LocationServiceMap>()("
     const image = Image.layer.pipe(Layer.provide(services))
     const mutation = FileMutation.locationLayer.pipe(Layer.provide(services))
     const skillGuidance = SkillGuidance.locationLayer.pipe(Layer.provide(services))
+    const referenceGuidance = ReferenceGuidance.locationLayer.pipe(Layer.provide(services))
     const todos = SessionTodo.layer.pipe(Layer.provide(services))
     const questions = QuestionV2.locationLayer.pipe(Layer.provide(services))
     const builtInTools = BuiltInTools.locationLayer.pipe(
@@ -89,10 +94,21 @@ export class LocationServiceMap extends LayerMap.Service<LocationServiceMap>()("
       Layer.provide(services),
       Layer.provide(model),
       Layer.provide(skillGuidance),
+      Layer.provide(referenceGuidance),
     )
-    return Layer.mergeAll(services, image, mutation, resources, todos, questions, model, runner, builtInTools).pipe(
-      Layer.fresh,
-    )
+    return Layer.mergeAll(
+      boot,
+      services,
+      image,
+      mutation,
+      resources,
+      todos,
+      questions,
+      model,
+      runner,
+      builtInTools,
+      referenceGuidance,
+    ).pipe(Layer.fresh)
   },
   idleTimeToLive: "60 minutes",
   dependencies: [

packages/core/src/location.ts

@@ -5,11 +5,10 @@ import { WorkspaceV2 } from "./workspace"
 
 export * as Location from "./location"
 
-export const Ref = Schema.Struct({
+export class Ref extends Schema.Class<Ref>("Location.Ref")({
   directory: AbsolutePath,
-  workspaceID: Schema.optional(WorkspaceV2.ID),
-}).annotate({ identifier: "Location.Ref" })
-export type Ref = typeof Ref.Type
+  workspaceID: Schema.optional(WorkspaceV2.ID).pipe(Schema.withConstructorDefault(Effect.succeed(undefined))),
+}) {}
 
 export class Info extends Schema.Class<Info>("Location.Info")({
   directory: AbsolutePath,

packages/core/src/plugin/skill/customize-opencode.md

@@ -73,6 +73,19 @@ Every field is optional.
     "urls": ["https://example.com/.well-known/skills/"]
   },
 
+  "references": {
+    "docs": {
+      "path": "../docs",
+      "description": "Use for product behavior and documentation conventions"
+    },
+    "sdk": {
+      "repository": "owner/sdk",
+      "branch": "main",
+      "description": "Use for SDK implementation details",
+      "hidden": true
+    }
+  },
+
   "agent": {
     "my-agent": {
       "model": "anthropic/claude-sonnet-4-6",
@@ -136,6 +149,7 @@ Shape notes worth being explicit about:
 
 - `model` always carries a provider prefix: `"anthropic/claude-sonnet-4-6"`.
 - `skills` is an object with `paths` and/or `urls`, not an array.
+- `references` is an object keyed by alias. Each value is a local path, Git repository, or string shorthand.
 - `agent` is an object keyed by agent name, not an array.
 - `plugin` is an array of strings or `[name, options]` tuples, not an object.
 - `mcp[name].command` is an array of strings, never a single string. `type` is required.
@@ -172,6 +186,38 @@ Register skills from non-default locations via `skills.paths` (scanned
 recursively for `**/SKILL.md`) and `skills.urls` (each URL serves a list of
 skills).
 
+## References
+
+References make local directories and Git repositories outside the active
+project available as supporting context. Configure them under `references`,
+keyed by the alias used in `@` autocomplete:
+
+```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 `path` values may be relative to the declaring config, absolute, or use
+`~/`. Git `repository` values accept Git URLs, host/path references, and GitHub
+`owner/repo` shorthand; `branch` is optional. Both forms support optional
+`description` and `hidden` fields.
+
+- Only references with a `description` are advertised to agents in system context.
+- `hidden: true` removes a reference from TUI `@` autocomplete only. It remains available to agents and by direct path.
+- Reference directories are automatically allowed through the external-directory boundary; normal read/edit/tool permissions still apply.
+- String shorthand is supported: use `"docs": "../docs"` for local paths or `"effect": "Effect-TS/effect"` for Git repositories.
+
 ## Agents
 
 Two ways to define an agent. Use the file form for anything non-trivial.

packages/core/src/reference.ts

@@ -9,21 +9,19 @@ import { RepositoryCache } from "./repository-cache"
 import { AbsolutePath } from "./schema"
 import { State } from "./state"
 
-export class Info extends Schema.Class<Info>("Reference.Info")({
-  name: Schema.String,
-  path: AbsolutePath,
-  source: Schema.suspend(() => Source),
-}) {}
-
 export class LocalSource extends Schema.Class<LocalSource>("Reference.LocalSource")({
   type: Schema.Literal("local"),
   path: AbsolutePath,
+  description: Schema.String.pipe(Schema.optional),
+  hidden: Schema.Boolean.pipe(Schema.optional),
 }) {}
 
 export class GitSource extends Schema.Class<GitSource>("Reference.GitSource")({
   type: Schema.Literal("git"),
   repository: Schema.String,
   branch: Schema.String.pipe(Schema.optional),
+  description: Schema.String.pipe(Schema.optional),
+  hidden: Schema.Boolean.pipe(Schema.optional),
 }) {}
 
 export const Source = Schema.Union([LocalSource, GitSource]).pipe(Schema.toTaggedUnion("type"))
@@ -33,6 +31,14 @@ export const Event = {
   Updated: EventV2.define({ type: "reference.updated", schema: {} }),
 }
 
+export class Info extends Schema.Class<Info>("Reference.Info")({
+  name: Schema.String,
+  path: AbsolutePath,
+  description: Schema.String.pipe(Schema.optional),
+  hidden: Schema.Boolean.pipe(Schema.optional),
+  source: Source,
+}) {}
+
 type Data = {
   sources: Map<string, Source>
 }
@@ -71,7 +77,16 @@ export const layer = Layer.effect(
           const seen = new Map<string, string | undefined>()
           for (const [name, source] of editor.list()) {
             if (source.type === "local") {
-              materialized.set(name, new Info({ name, path: source.path, source }))
+              materialized.set(
+                name,
+                new Info({
+                  name,
+                  path: source.path,
+                  description: source.description,
+                  hidden: source.hidden,
+                  source,
+                }),
+              )
               continue
             }
             const repository = Repository.parse(source.repository)
@@ -86,7 +101,16 @@ export const layer = Layer.effect(
             const target = Repository.cachePath(global.repos, repository)
             if (seen.has(target) && seen.get(target) !== source.branch) continue
             seen.set(target, source.branch)
-            materialized.set(name, new Info({ name, path: AbsolutePath.make(target), source }))
+            materialized.set(
+              name,
+              new Info({
+                name,
+                path: AbsolutePath.make(target),
+                description: source.description,
+                hidden: source.hidden,
+                source,
+              }),
+            )
             yield* cache.ensure({ reference: repository, branch: source.branch, refresh: true }).pipe(
               Effect.catchCause((cause) =>
                 Effect.logWarning("failed to materialize reference", {

packages/core/src/reference/guidance.ts

@@ -0,0 +1,69 @@
+export * as ReferenceGuidance from "./guidance"
+
+import { Context, Effect, Layer, Schema } from "effect"
+import { PluginBoot } from "../plugin/boot"
+import { Reference } from "../reference"
+import { SystemContext } from "../system-context/index"
+
+const Summary = Schema.Struct({
+  name: Schema.String,
+  path: Schema.String,
+  description: Schema.String.pipe(Schema.optional),
+})
+
+const render = (references: ReadonlyArray<typeof Summary.Type>) =>
+  [
+    "Project references provide additional directories that can be accessed when relevant.",
+    "<available_references>",
+    ...references.flatMap((reference) => [
+      "  <reference>",
+      `    <name>${reference.name}</name>`,
+      `    <path>${reference.path}</path>`,
+      ...(reference.description === undefined ? [] : [`    <description>${reference.description}</description>`]),
+      "  </reference>",
+    ]),
+    "</available_references>",
+  ].join("\n")
+
+export interface Interface {
+  readonly load: () => Effect.Effect<SystemContext.SystemContext>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/v2/ReferenceGuidance") {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const boot = yield* PluginBoot.Service
+    const references = yield* Reference.Service
+
+    return Service.of({
+      load: Effect.fn("ReferenceGuidance.load")(function* () {
+        yield* boot.wait()
+        const available = (yield* references.list())
+          .filter((reference) => reference.description !== undefined)
+          .map((reference) => ({
+            name: reference.name,
+            path: reference.path,
+            description: reference.description,
+          }))
+          .toSorted((a, b) => a.name.localeCompare(b.name))
+        if (available.length === 0) return SystemContext.empty
+        return SystemContext.make({
+          key: SystemContext.Key.make("core/reference-guidance"),
+          codec: Schema.toCodecJson(Schema.Array(Summary)),
+          load: Effect.succeed(available),
+          baseline: render,
+          update: (_previous, current) =>
+            [
+              "The available project references have changed. This list supersedes the previous reference list.",
+              render(current),
+            ].join("\n"),
+          removed: () => "Project reference guidance is no longer available. Do not use previously listed references.",
+        })
+      }),
+    })
+  }),
+)
+
+export const locationLayer = layer

packages/core/src/ripgrep.ts

@@ -161,10 +161,10 @@ export const layer = Layer.effect(
           args: [
             "--no-config",
             "--files",
-            "--glob=!**/.git/**",
             ...(input.hidden ? ["--hidden"] : []),
             ...(input.follow ? ["--follow"] : []),
             `--glob=${input.pattern}`,
+            "--glob=!**/.git/**",
             ".",
           ],
           parse: (line) =>
@@ -195,10 +195,10 @@ export const layer = Layer.effect(
           args: [
             "--no-config",
             "--files",
-            "--glob=!**/.git/**",
             ...(input.hidden ? ["--hidden"] : []),
             ...(input.follow ? ["--follow"] : []),
-            `--glob=${input.pattern}`,
+            ...(input.pattern === "*" ? [] : [`--glob=${input.pattern}`]),
+            "--glob=!**/.git/**",
             ".",
           ],
           parse: (line) => {
@@ -226,9 +226,9 @@ export const layer = Layer.effect(
             "--no-config",
             "--json",
             "--hidden",
-            "--glob=!**/.git/**",
             "--no-messages",
             ...(input.include ? [`--glob=${input.include}`] : []),
+            "--glob=!**/.git/**",
             "--",
             input.pattern,
             input.file ?? ".",

packages/core/src/session/runner/llm.ts

@@ -19,6 +19,7 @@ import { QuestionV2 } from "../../question"
 import { SystemContext } from "../../system-context/index"
 import { SystemContextRegistry } from "../../system-context/registry"
 import { SkillGuidance } from "../../skill/guidance"
+import { ReferenceGuidance } from "../../reference/guidance"
 import { ToolRegistry } from "../../tool/registry"
 import { ToolOutputStore } from "../../tool-output-store"
 import { SessionContextEpoch } from "../context-epoch"
@@ -98,6 +99,7 @@ export const layer = Layer.effect(
     const location = yield* Location.Service
     const systemContext = yield* SystemContextRegistry.Service
     const skillGuidance = yield* SkillGuidance.Service
+    const referenceGuidance = yield* ReferenceGuidance.Service
     const config = yield* Config.Service
     const db = (yield* Database.Service).db
     const compaction = SessionCompaction.make({ events, llm, config: yield* config.entries() })
@@ -166,9 +168,9 @@ export const layer = Layer.effect(
 
     const sameModel = Schema.toEquivalence(Schema.UndefinedOr(ModelV2.Ref))
     const loadSystemContext = (agent: AgentV2.Selection) =>
-      Effect.all([systemContext.load(), skillGuidance.load(agent)], { concurrency: "unbounded" }).pipe(
-        Effect.map(SystemContext.combine),
-      )
+      Effect.all([systemContext.load(), skillGuidance.load(agent), referenceGuidance.load()], {
+        concurrency: "unbounded",
+      }).pipe(Effect.map(SystemContext.combine))
 
     const runTurnAttempt = Effect.fn("SessionRunner.runTurn")(function* (
       sessionID: SessionSchema.ID,

packages/core/src/v1/config/config.ts

@@ -3,6 +3,7 @@ export * as ConfigV1 from "./config"
 import { Schema } from "effect"
 import { NonNegativeInt, PositiveInt, type DeepMutable } from "../../schema"
 import { ConfigExperimental } from "../../config/experimental"
+import { ConfigReference } from "../../config/reference"
 import { ConfigAgentV1 } from "./agent"
 import { ConfigAttachmentV1 } from "./attachment"
 import { ConfigCommandV1 } from "./command"
@@ -13,7 +14,6 @@ import { ConfigMCPV1 } from "./mcp"
 import { ConfigPermissionV1 } from "./permission"
 import { ConfigPluginV1 } from "./plugin"
 import { ConfigProviderV1 } from "./provider"
-import { ConfigReferenceV1 } from "./reference"
 import { ConfigServerV1 } from "./server"
 import { ConfigSkillsV1 } from "./skills"
 
@@ -42,7 +42,7 @@ export const Info = Schema.Struct({
     description: "Command configuration, see https://opencode.ai/docs/commands",
   }),
   skills: Schema.optional(ConfigSkillsV1.Info).annotate({ description: "Additional skill folder paths" }),
-  reference: Schema.optional(ConfigReferenceV1.Info).annotate({
+  references: Schema.optional(ConfigReference.Info).annotate({
     description: "Named git or local directory references",
   }),
   watcher: Schema.optional(Schema.Struct({ ignore: Schema.optional(Schema.mutable(Schema.Array(Schema.String))) })),

packages/core/src/v1/config/migrate.ts

@@ -12,7 +12,6 @@ const keys = new Set([
   "logLevel",
   "server",
   "command",
-  "reference",
   "snapshot",
   "plugin",
   "autoshare",
@@ -63,7 +62,7 @@ export function migrate(info: typeof ConfigV1.Info.Type) {
     skills: info.skills && [...(info.skills.paths ?? []), ...(info.skills.urls ?? [])],
     commands: info.command,
     instructions: info.instructions,
-    references: info.reference,
+    references: info.references,
     plugins: info.plugin?.map((plugin) =>
       typeof plugin === "string" ? plugin : { package: plugin[0], options: plugin[1] },
     ),

packages/core/src/v1/config/reference.ts

@@ -1,24 +0,0 @@
-export * as ConfigReferenceV1 from "./reference"
-
-import { Schema } from "effect"
-
-const Git = Schema.Struct({
-  repository: Schema.String.annotate({
-    description: "Git repository URL, host/path reference, or GitHub owner/repo shorthand",
-  }),
-  branch: Schema.optional(Schema.String).annotate({
-    description: "Branch or ref to clone and inspect",
-  }),
-})
-
-const Local = Schema.Struct({
-  path: Schema.String.annotate({
-    description: "Absolute path, ~/ path, or workspace-relative path to a local reference directory",
-  }),
-})
-
-export const Entry = Schema.Union([Schema.String, Git, Local]).annotate({ identifier: "ReferenceConfigEntry" })
-export type Entry = Schema.Schema.Type<typeof Entry>
-
-export const Info = Schema.Record(Schema.String, Entry).annotate({ identifier: "ReferenceConfig" })
-export type Info = Schema.Schema.Type<typeof Info>