From 892b05362476c6a5fdc805ca4886798e8e69b256 Mon Sep 17 00:00:00 2001
From: Darren Hinde <107584450+darrenhinde@users.noreply.github.com>
Date: Fri, 6 Feb 2026 01:14:08 +0000
Subject: [PATCH] fix: ContextScout global fallback for core files + context
 resolution docs (#175, #177) (#186)

* fix: ContextScout falls back to global core/ when local core/ missing

Users who install OAC globally have core standards at
~/.config/opencode/context/core/ but no local core/ directory.
ContextScout now does a one-time check on startup: if local
core/navigation.md doesn't exist, it checks the global path
from paths.json. This resolves the ENOENT errors when agents
try to read core/standards/ files that only exist globally.

- paths.json: enabled global path (~/.config/opencode/context)
- contextscout.md: added global_fallback rule with 2-glob cap
- Fallback is ONLY for core/ files, never project-intelligence

* docs: add context resolution explanation to README

Explains how ContextScout resolves context files: local-first,
global fallback only for core/ files, project-intelligence always
local. Includes flow diagram, key rules, and common setup table.
---
 .../agent/subagents/core/contextscout.md      | 21 ++++++++++++---
 .opencode/context/core/config/paths.json      |  2 +-
 README.md                                     | 27 +++++++++++++++++++
 3 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/.opencode/agent/subagents/core/contextscout.md b/.opencode/agent/subagents/core/contextscout.md
index 32f93bc..667b192 100644
--- a/.opencode/agent/subagents/core/contextscout.md
+++ b/.opencode/agent/subagents/core/contextscout.md
@@ -27,6 +27,17 @@ permission:
   <rule id="context_root">
     The context root is determined by paths.json (loaded via @ reference). Default is `.opencode/context/`. If custom_dir is set in paths.json, use that instead. Start by reading `{context_root}/navigation.md`. Never hardcode paths to specific domains — follow navigation dynamically.
   </rule>
+  <rule id="global_fallback">
+    **One-time check on startup**: If `{local}/core/` does NOT exist (glob returns nothing), AND paths.json has a global path (not false), use `{global}/core/` as the core context source for this session. This handles users who installed OAC globally but work in a local project.
+
+    Resolution steps (run ONCE, at the start of every invocation):
+    1. `glob("{local}/core/navigation.md")` — if found → local has core, use `{local}` for everything. Done.
+    2. If not found → read paths.json `global` value. If false or missing → no fallback, proceed with local only.
+    3. If global path exists → `glob("{global}/core/navigation.md")` — if found → use `{global}/core/` for core files only.
+    4. Set `{core_root}` = whichever path has core. All other context (project-intelligence, ui, etc.) stays `{local}`.
+
+    **Limits**: This is ONLY for `core/` files (standards, workflows, guides). Never fall back to global for project-intelligence — that's project-specific. Maximum 2 glob checks. No per-file fallback.
+  </rule>
   <rule id="read_only">
     Read-only agent. NEVER use write, edit, bash, task, or any tool besides read, grep, glob.
   </rule>
@@ -38,6 +49,7 @@ permission:
   </rule>
   <tier level="1" desc="Critical Operations">
     - @context_root: Navigation-driven discovery only — no hardcoded paths
+    - @global_fallback: Resolve core location once at startup (max 2 glob checks)
     - @read_only: Only read, grep, glob — nothing else
     - @verify_before_recommend: Confirm every path exists before returning it
     - @external_scout_trigger: Recommend ExternalScout when library not found internally
@@ -56,11 +68,12 @@ permission:
 
 ## How It Works
 
-**3 steps. That's it.**
+**4 steps. That's it.**
 
-1. **Understand intent** — What is the user trying to do?
-2. **Follow navigation** — Read `navigation.md` files from `.opencode/context/` downward. They are the map.
-3. **Return ranked files** — Priority order: Critical → High → Medium. Brief summary per file.
+1. **Resolve core location** (once) — Check if `{local}/core/navigation.md` exists. If not, check `{global}/core/navigation.md` per @global_fallback. Set `{core_root}` accordingly.
+2. **Understand intent** — What is the user trying to do?
+3. **Follow navigation** — Read `navigation.md` files from `{local}` (and `{core_root}` if different) downward. They are the map.
+4. **Return ranked files** — Priority order: Critical → High → Medium. Brief summary per file. Use the actual resolved path (local or global) in file paths.
 
 ## Response Format
 
diff --git a/.opencode/context/core/config/paths.json b/.opencode/context/core/config/paths.json
index fe4dd13..9f18491 100644
--- a/.opencode/context/core/config/paths.json
+++ b/.opencode/context/core/config/paths.json
@@ -2,6 +2,6 @@
   "description": "Additional context file paths - agents load this via @ reference for dynamic pathing",
   "paths": {
     "local": ".opencode/context",
-    "global": false
+    "global": "~/.config/opencode/context"
   }
 }
diff --git a/README.md b/README.md
index 6b21486..efb70df 100644
--- a/README.md
+++ b/README.md
@@ -417,6 +417,33 @@ Your coding standards automatically loaded by agents:
 - Team-ready (commit to repo)
 - Version controlled (track changes)
 
+### How Context Resolution Works
+
+ContextScout discovers context files using a **local-first** approach:
+
+```
+1. Check local: .opencode/context/core/navigation.md
+   ↓ Found? → Use local for everything. Done.
+   ↓ Not found?
+2. Check global: ~/.config/opencode/context/core/navigation.md
+   ↓ Found? → Use global for core/ files only.
+   ↓ Not found? → Proceed without core context.
+```
+
+**Key rules:**
+- **Local always wins** — if you installed locally, global is never checked
+- **Global fallback is only for `core/`** (standards, workflows, guides) — universal files that are the same across projects
+- **Project intelligence is always local** — your tech stack, patterns, and naming conventions live in `.opencode/context/project-intelligence/` and are never loaded from global
+- **One-time check** — ContextScout resolves the core location once at startup (max 2 glob checks), not per-file
+
+**Common setups:**
+
+| Setup | Core files from | Project intelligence from |
+|-------|----------------|--------------------------|
+| Local install (`bash install.sh developer`) | `.opencode/context/core/` | `.opencode/context/project-intelligence/` |
+| Global install + `/add-context` | `~/.config/opencode/context/core/` | `.opencode/context/project-intelligence/` |
+| Both local and global | `.opencode/context/core/` (local wins) | `.opencode/context/project-intelligence/` |
+
 ---