fix: correct context path defaults and add preview gates (Issues #175 , #177 ) (#183 )

- /add-context now always saves to local .opencode/context/project-intelligence/
  with --global flag as opt-in for ~/.config/opencode/ (fixes #175)
- Added Stage 0.5 path resolution, full file preview before writes,
  Replace All backup preview, and navigation.md preview (fixes #177)
- Rewrote context-paths.md with resolution order, merging rules, scenarios
- Added /context migrate operation for global-to-local migration
- Added preview/approval gates to creation, harvest, and extract operations
- Updated README, CONTEXT_SYSTEM_GUIDE, platform-compatibility docs
- All stale ~/.opencode/ and project-context.md references removed

2026-02-06 01:01:25 +00:00

3.2 KiB

Raw Blame History

id	name
context-paths	Context File Path Resolution

Context File Path Resolution

Resolution Order

Context files are resolved in this order (later sources override earlier ones for conflicting keys):

Global context (~/.config/opencode/context/) — user-wide defaults
Local context (.opencode/context/ in project root) — project-specific, highest priority

This mirrors OpenCode's own config merging behavior (see OpenCode Config Docs).

What Goes Where

Content Type	Recommended Location	Why
Project Intelligence (tech stack, patterns, naming)	Local `.opencode/context/project-intelligence/`	Project-specific, committed to git, shared with team
Core Standards (code-quality, docs, tests)	Wherever OAC was installed	Universal standards, same across projects
Personal Defaults (your preferred patterns)	Global `~/.config/opencode/context/project-intelligence/`	Personal coding style across all projects

How Merging Works

If a file exists in both local and global, the local version wins
If a file exists only in global, it's still loaded (acts as a fallback)
If a file exists only in local, it's loaded normally

Example: User installs OAC globally (core standards at ~/.config/opencode/context/core/), then runs /add-context in a project (creates .opencode/context/project-intelligence/ locally). The agent loads both: core standards from global, project intelligence from local.

Path Configuration

{
  "paths": {
    "local": ".opencode/context",
    "global": "~/.config/opencode/context"
  }
}

Set "global": false to disable global context loading.

Environment Variable Override

The installer supports OPENCODE_INSTALL_DIR to override the install location:

export OPENCODE_INSTALL_DIR=~/custom/path
bash install.sh developer

OpenCode itself supports OPENCODE_CONFIG_DIR for a custom config directory (see OpenCode docs). If set, context files in that directory are loaded alongside global and local configs.

Migrating Global to Local

If you installed globally but want project-specific context:

/context migrate

This copies project-intelligence/ from global (~/.config/opencode/context/) to local (.opencode/context/), so your project patterns are committed to git and shared with your team. See /context migrate for details.

Common Scenarios

Scenario 1: Everything Local (Development / Repo Maintainer)

OAC installed locally via bash install.sh developer
All context in .opencode/context/
Committed to git, team shares everything

Scenario 2: Global Install + Local Project Intelligence

OAC installed globally via bash install.sh developer --install-dir ~/.config/opencode
Core standards at ~/.config/opencode/context/core/
Run /add-context in project → creates .opencode/context/project-intelligence/ locally
Project intelligence committed to git, core standards come from global

Scenario 3: Global Personal Defaults

Run /add-context --global to save personal coding patterns
These apply to ALL projects as fallback
Any project can override with local /add-context

3.2 KiB Raw Blame History