docs: expand user guides

packages/docs/instructions.mdx

@@ -0,0 +1,124 @@
+---
+title: "Instructions"
+description: "Give OpenCode global, project, and directory-specific guidance."
+---
+
+Instructions are privileged context that guide an agent throughout a session.
+V2 combines built-in context, discovered `AGENTS.md` files, and dynamic sources
+such as skill, reference, MCP, and session context into a durable instruction
+baseline.
+
+## AGENTS.md
+
+Use `AGENTS.md` for persistent guidance such as build commands, architecture,
+code conventions, and verification requirements. Commit project files so the
+whole team receives the same instructions.
+
+V2 loads:
+
+1. The global file at `$XDG_CONFIG_HOME/opencode/AGENTS.md`, normally
+   `~/.config/opencode/AGENTS.md`.
+2. Every `AGENTS.md` from the current Location up to and including the project
+   root.
+
+For example, when the Location is `packages/web`, OpenCode can load all three
+project files below:
+
+```text
+my-project/
+├── AGENTS.md
+└── packages/
+    ├── AGENTS.md
+    └── web/
+        └── AGENTS.md
+```
+
+The files are combined rather than selecting a single winner. They are rendered
+in this order: global, then project files from the Location toward the project
+root. OpenCode does not resolve conflicts between their contents, so keep broad
+guidance global and put scoped guidance in the relevant project directory.
+
+If the Location is outside the project root, only the global file is loaded.
+Setting `OPENCODE_DISABLE_PROJECT_CONFIG=1` also skips project `AGENTS.md`
+discovery but does not disable the global file.
+
+<Note>
+  Current V2 discovery only recognizes `AGENTS.md`. The `CLAUDE.md` fallback
+  and related precedence described by older OpenCode documentation do not apply.
+</Note>
+
+### Nested instructions
+
+An `AGENTS.md` below the Location is not part of the initial upward scan. When
+the read tool successfully reads a file or lists a directory, OpenCode discovers
+`AGENTS.md` files from that target upward to, but not including, the Location.
+It adds newly discovered files to the session in nearest-first order.
+
+Each nested file is injected once per session and recorded in durable session
+history. Reading the same area again does not inject it again. Consequently,
+editing an already injected nested `AGENTS.md` does not replace its earlier
+session entry automatically; start a new session if the updated text must apply
+immediately.
+
+## Config entries
+
+The V2 config schema accepts an `instructions` array of strings:
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "CONTRIBUTING.md",
+    "docs/guidelines/*.md",
+    "https://example.com/shared-instructions.md"
+  ]
+}
+```
+
+Configuration is loaded from global through project-local files. If more than
+one config defines `instructions`, the highest-precedence, closest config's
+entire array is selected; arrays are not merged.
+
+<Warning>
+  V2 currently parses and retains this field but does not resolve its entries
+  into instruction sources. Local files, glob patterns, and HTTP or HTTPS URLs
+  in `instructions` therefore do not reach the model yet. Use `AGENTS.md` for
+  active V2 instructions. URL fetching and timeout behavior documented for V1
+  are not supported by the current V2 implementation.
+</Warning>
+
+See [Config](/config) for config locations and general precedence.
+
+## Ordering
+
+The selected agent or provider system prompt is sent first. OpenCode then sends
+the session's instruction baseline, composed in this order:
+
+1. Built-in environment and date context.
+2. Ambient `AGENTS.md` discovery.
+3. Available skill, reference, and MCP guidance.
+4. Session-specific instruction entries supplied through the API.
+
+These sources are combined; ordering is not an override mechanism. Nested
+`AGENTS.md` files discovered by reads are chronological session entries rather
+than part of the baseline.
+
+## Changes
+
+Before each model step, V2 compares live instruction sources with what that
+session's model was last told:
+
+- A new or changed ambient `AGENTS.md` aggregate is announced as a system update
+  that replaces the previous ambient aggregate.
+- Removing all ambient files announces that the previous ambient instructions
+  no longer apply.
+- A temporary read or discovery failure preserves the session's last known
+  instructions instead of treating them as deleted. If no baseline exists yet,
+  the first model step waits until required sources are available.
+- Completed conversation compaction creates a fresh baseline from the current
+  sources. Moving a session or committing a revert also resets its instruction
+  checkpoint so the next step establishes a new baseline.
+
+Updates are durable session history. OpenCode does not rewrite the original
+baseline on every change; it records the change so subsequent model steps see
+both the established baseline and the chronological update.