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

- /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

.opencode/command/add-context.md

@@ -85,10 +85,11 @@ Help users add project patterns using Project Intelligence standard. **Easiest w
 ## Usage
 
 ```bash
-/add-context                 # Interactive wizard (recommended)
+/add-context                 # Interactive wizard (recommended, saves to project)
 /add-context --update        # Update existing context
 /add-context --tech-stack    # Add/update tech stack only
 /add-context --patterns      # Add/update code patterns only
+/add-context --global        # Save to global config (~/.config/opencode/) instead of project
 ```
 
 ---
@@ -98,11 +99,13 @@ Help users add project patterns using Project Intelligence standard. **Easiest w
 **Run**: `/add-context`
 
 **What happens**:
-1. Checks for external context files in `.tmp/` (if found, offers to extract)
-2. Checks for existing project intelligence
-3. Asks 6 questions (~5 min) OR reviews existing patterns
-4. Generates/updates technical-domain.md
-5. Agents now use YOUR patterns
+1. Saves to `.opencode/context/project-intelligence/` in your project (always local)
+2. Checks for external context files in `.tmp/` (if found, offers to extract)
+3. Checks for existing project intelligence
+4. Asks 6 questions (~5 min) OR reviews existing patterns
+5. Shows full preview of files to be created before writing
+6. Generates/updates technical-domain.md + navigation.md
+7. Agents now use YOUR patterns
 
 **6 Questions** (~5 min):
 1. Tech stack?
@@ -124,6 +127,23 @@ Help users add project patterns using Project Intelligence standard. **Easiest w
 
 ## Workflow
 
+### Stage 0.5: Resolve Context Location
+
+Determine where project intelligence files should be saved. This runs BEFORE anything else.
+
+**Default behavior**: Always use local `.opencode/context/project-intelligence/`.
+**Override**: `--global` flag saves to `~/.config/opencode/context/project-intelligence/` instead.
+
+**Resolution:**
+1. If `--global` flag → `$CONTEXT_DIR = ~/.config/opencode/context/project-intelligence/`
+2. Otherwise → `$CONTEXT_DIR = .opencode/context/project-intelligence/` (always local)
+
+**If `.opencode/context/` doesn't exist yet**, create it silently — no prompt needed. The directory structure is part of the output shown in Stage 4.
+
+**Variable**: `$CONTEXT_DIR` is set here and used in all subsequent stages.
+
+---
+
 ### Stage 0: Check for External Context Files
 
 Check: `.tmp/` directory for external context files (e.g., `.tmp/external-context.md`, `.tmp/context-*.md`)
@@ -180,7 +200,7 @@ Ready to harvest? [y/n]: _
 
 ### Stage 1: Detect Existing Context
 
-Check: `~/.opencode/context/project-intelligence/`
+Check: `$CONTEXT_DIR` (set in Stage 0.5 — either `.opencode/context/project-intelligence/` or `~/.config/opencode/context/project-intelligence/`)
 
 **If exists**:
 ```
@@ -206,18 +226,41 @@ Current patterns:
 Options:
   1. Review and update patterns (show each one)
   2. Add new patterns (keep all existing)
-  3. Replace all patterns (start fresh, backup old)
+  3. Replace all patterns (start fresh)
   4. Cancel
 
 Choose [1/2/3/4]: _
 ```
 
+**If user chooses 3 (Replace all):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Replace All: Preview
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Will BACKUP existing files to:
+  .tmp/backup/project-intelligence-{timestamp}/
+    ← technical-domain.md (Version: 1.2)
+    ← business-domain.md (Version: 1.0)
+    ← navigation.md
+
+Will DELETE and RECREATE:
+  $CONTEXT_DIR/technical-domain.md (new Version: 1.0)
+  $CONTEXT_DIR/navigation.md (new Version: 1.0)
+
+Existing files backed up → you can restore from .tmp/backup/ if needed.
+
+Proceed? [y/n]: _
+```
+
 **If not exists**:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 No project intelligence found. Let's create it!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Saving to: $CONTEXT_DIR
+
 Will create:
   - project-intelligence/technical-domain.md (tech stack & patterns)
   - project-intelligence/navigation.md (quick overview)
@@ -485,7 +528,7 @@ Preview: technical-domain.md
 Size: {line_count} lines (limit: 200 per @mvi_compliance)
 Status: ✅ MVI compliant
 
-Save to: ~/.opencode/context/project-intelligence/technical-domain.md
+Save to: $CONTEXT_DIR/technical-domain.md
 
 Looks good? [y/n/edit]: _
 ```
@@ -511,12 +554,35 @@ Running validation...
 ✅ Version set: 1.0 (@version_tracking)
 ✅ MVI compliant (<30s scannable)
 ✅ No duplication
+```
+
+**navigation.md preview** (also created/updated):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Preview: navigation.md
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Creating files per @project_intelligence...
-  ✓ technical-domain.md
-  ✓ navigation.md (updated per @navigation_update)
+# Project Intelligence
 
-Done!
+| File | Description | Priority |
+|------|-------------|----------|
+| [technical-domain.md](technical-domain.md) | Tech stack & patterns | critical |
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Full creation plan**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Files to write:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  CREATE  $CONTEXT_DIR/technical-domain.md ({line_count} lines)
+  CREATE  $CONTEXT_DIR/navigation.md ({nav_line_count} lines)
+
+Total: 2 files
+
+Proceed? [y/n]: _
 ```
 
 ---
@@ -529,9 +595,10 @@ Done!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Files created:
-  ~/.opencode/context/project-intelligence/technical-domain.md
-  ~/.opencode/context/project-intelligence/navigation.md
+  $CONTEXT_DIR/technical-domain.md
+  $CONTEXT_DIR/navigation.md
 
+Location: $CONTEXT_DIR
 Agents now use YOUR patterns automatically!
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -543,7 +610,7 @@ What's next?
    > "Create API endpoint"
    (Uses YOUR pattern!)
 
-2. Review: cat ~/.opencode/context/project-intelligence/technical-domain.md
+2. Review: cat $CONTEXT_DIR/technical-domain.md
 
 3. Add business context: /add-context --business
 
@@ -560,6 +627,18 @@ When you:
 
 Agents stay synced!
 
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 Tip: Global patterns
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Want the same patterns across ALL your projects?
+  /add-context --global
+  → Saves to ~/.config/opencode/context/project-intelligence/
+  → Acts as fallback for projects without local context
+
+Already have global patterns? Bring them into this project:
+  /context migrate
+
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📚 Learn More
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -593,7 +672,7 @@ Agents stay synced!
 ### Pattern Detection (Stage 1)
 
 **Process**:
-1. Check: `ls ~/.opencode/context/project-intelligence/`
+1. Check: `ls $CONTEXT_DIR/` (path determined in Stage 0.5)
 2. Read: `cat technical-domain.md` (if exists)
 3. Parse existing patterns:
    - Frontmatter: version, updated date
@@ -822,16 +901,22 @@ Check code & retry.
 A: Check file exists, <200 lines. Run `/context validate`
 
 **Q: See what's in context?**
-A: `cat ~/.opencode/context/project-intelligence/technical-domain.md`
+A: `cat .opencode/context/project-intelligence/technical-domain.md` (local) or `cat ~/.config/opencode/context/project-intelligence/technical-domain.md` (global)
 
 **Q: Multiple context files?**
-A: Yes! Create in `~/.opencode/context/project-intelligence/`. Agents load all.
+A: Yes! Create in your project-intelligence directory. Agents load all.
 
 **Q: Remove pattern?**
-A: Edit directly: `nano ~/.opencode/context/project-intelligence/technical-domain.md`
+A: Edit directly: `nano .opencode/context/project-intelligence/technical-domain.md`
 
 **Q: Share w/ team?**
-A: Yes! Commit `~/.opencode/context/project-intelligence/` to repo.
+A: Yes! Use local install (`.opencode/context/project-intelligence/`) and commit to repo. Team members get your patterns automatically.
+
+**Q: Local vs global?**
+A: Local (`.opencode/`) = project-specific, committed to git, team-shared. Global (`~/.config/opencode/`) = personal defaults across all projects. Local overrides global.
+
+**Q: Installed globally but want project patterns?**
+A: Run `/add-context` (defaults to local). Creates `.opencode/context/project-intelligence/` in your project even if OAC was installed globally.
 
 **Q: Have external context files in .tmp/?**
 A: Run `/context harvest` to extract and organize them into permanent context

.opencode/command/context.md

@@ -127,6 +127,17 @@ When invoked without arguments: `/context`
 
 ---
 
+### Migration
+
+**`/context migrate`**
+- Copy project-intelligence from global (`~/.config/opencode/context/`) to local (`.opencode/context/`)
+- For users who installed globally but want project-specific, git-committed context
+- Shows diff if local files already exist, asks before overwriting
+- Optionally cleans up global project-intelligence after migration
+- **Reads**: `standards/mvi.md`
+
+---
+
 ### Utility Operations
 
 **`/context map [category]`**
@@ -174,6 +185,10 @@ When invoked without arguments: `/context`
   <operation name="create">
     Read: guides/creation.md, standards/structure.md, standards/templates.md
   </operation>
+  
+  <operation name="migrate">
+    Read: standards/mvi.md
+  </operation>
 </lazy_load_map>
 
 **All files located in**: `.opencode/context/core/context-system/`
@@ -184,7 +199,7 @@ When invoked without arguments: `/context`
 
 <subagent_routing>
   <!-- Delegate operations to specialized subagents -->
-  <route operations="harvest|extract|organize|update|error|create" to="ContextOrganizer">
+  <route operations="harvest|extract|organize|update|error|create|migrate" to="ContextOrganizer">
     Pass: operation name, arguments, lazy load map
     Subagent loads: Required context files from .opencode/context/core/context-system/
     Subagent executes: Multi-stage workflow per operation
@@ -261,6 +276,13 @@ When invoked without arguments: `/context`
 /context update for React 19 breaking changes
 ```
 
+### Migrate Global to Local
+```bash
+/context migrate
+# Copies project-intelligence from ~/.config/opencode/context/ to .opencode/context/
+# Shows what will be copied, asks for approval before proceeding
+```
+
 ---
 
 ## Success Criteria

.opencode/context/core/context-system.md

@@ -432,8 +432,17 @@ Data:     development/data/nosql-patterns/mongodb.md
 ## Quick Commands
 
 ```bash
-/context harvest              # Clean up summaries
-/context extract {source}     # From docs/code
-/context organize {category}  # Restructure
-/context update {what}        # When APIs change
+/context                      # Quick scan, suggest actions
+/context harvest              # Clean up summaries → permanent context
+/context extract {source}     # From docs/code/URLs
+/context organize {category}  # Restructure flat files → function folders
+/context update {what}        # When APIs/frameworks change
+/context migrate              # Move global project-intelligence → local project
+/context create {category}    # Create new context category
+/context error {error}        # Add recurring error to knowledge base
+/context compact {file}       # Minimize verbose file to MVI format
+/context map [category]       # View context structure
+/context validate             # Check integrity, references, sizes
 ```
+
+**All operations show a preview of what will be created/moved/deleted before asking for approval.**

.opencode/context/core/context-system/guides/creation.md

@@ -55,15 +55,76 @@
     Link to related concepts/, examples/, guides/, errors/
   </stage>
   
-  <stage id="6" name="Update README">
-    Add entry to category README.md navigation table
+  <stage id="6" name="Preview &amp; Approve" enforce="@critical_rules.approval_gate">
+    MUST show full preview before writing ANY files:
+
+    ```
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    Preview: File Creation Plan
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    CREATE file:
+      {category}/{function}/{filename}.md ({line_count} lines)
+
+    Content preview:
+    ┌─────────────────────────────────────────────────────────┐
+    │ # {Type}: {Name}                                        │
+    │                                                         │
+    │ **Purpose**: {1 sentence}                               │
+    │ **Last Updated**: {date}                                │
+    │                                                         │
+    │ ## Core Concept                                         │
+    │ {1-3 sentences}                                         │
+    │                                                         │
+    │ ## Key Points                                           │
+    │ {3-5 bullets}                                           │
+    │ ...                                                     │
+    └─────────────────────────────────────────────────────────┘
+
+    UPDATE navigation:
+      {category}/navigation.md
+        + | [{filename}.md]({function}/{filename}.md) | {desc} | {priority} |
+
+    Validation:
+      ✓ {line_count} lines (limit: {max_lines} for {type})
+      ✓ MVI format applied
+      ✓ Correct folder: {function}/
+      ✓ Cross-references: {count} links added
+
+    Approve? [y/n/edit]: _
+    ```
+
+    If file already exists at target path:
+    ```
+    ⚠️  File already exists: {category}/{function}/{filename}.md
+
+    Options:
+      1. Cancel (keep existing)
+      2. Show diff (compare existing vs new)
+      3. Overwrite (replace existing)
+      4. Rename new file to {filename}-v2.md
+
+    Choose [1/2/3/4]: _
+    ```
   </stage>
   
-  <stage id="7" name="Verify">
+  <stage id="7" name="Write &amp; Report">
+    Only after approval:
+    1. Write file to disk
+    2. Update navigation.md
+    3. Show confirmation:
+
+    ```
+    ✅ Created: {category}/{function}/{filename}.md ({line_count} lines)
+    ✅ Updated: {category}/navigation.md
+    ```
+  </stage>
+  
+  <stage id="8" name="Verify">
     - [ ] <200 lines?
     - [ ] MVI format?
     - [ ] Correct folder?
-    - [ ] README updated?
+    - [ ] navigation.md updated?
     - [ ] Cross-refs added?
   </stage>
 </workflow>

.opencode/context/core/context-system/navigation.md

@@ -28,6 +28,7 @@ core/context-system/
 | **Operations & procedures** | `./operations/` |
 | **Implementation guides** | `./guides/` |
 | **Standards & templates** | `./standards/navigation.md` |
+| **Migrate global → local** | `./operations/migrate.md` |
 
 ---
 

.opencode/context/core/context-system/operations/extract.md

@@ -73,23 +73,49 @@ Select items (A B I or 'all') + category (1/2/3):
 ---
 
 ### Stage 4: Preview (APPROVAL REQUIRED)
-**Action**: Show what will be created
+**Action**: Show what will be created, check for conflicts
 
 **Format**:
 ```
-Would create in development/:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Extraction Plan: development/
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+CREATE (new files):
   concepts/use-state.md (45 lines)
   concepts/use-effect.md (52 lines)
-  errors/react-hooks-errors.md (124 lines)
+  concepts/use-context.md (38 lines)
+  ... (6 more)
+  guides/custom-hooks.md (87 lines)
+  guides/debugging-hooks.md (65 lines)
+
+ADD TO (existing files):
+  errors/react-hooks-errors.md (98 → 124 lines)
+    + 4 new error entries
+
+⚠️  CONFLICT (file already exists):
+  concepts/use-memo.md already exists (42 lines)
+    Options:
+      [A] Skip — keep existing file
+      [B] Overwrite — replace with extracted version
+      [C] Merge — add new content to existing file (42 → 58 lines)
+    Choose [A/B/C]: _
+
+NAVIGATION UPDATE:
+  development/navigation.md
+    + 9 new entries in Concepts table
+    + 2 new entries in Guides table
+    + 1 updated entry in Errors table
 
 Total: 12 files, ~650 lines
 
-Preview file? (type filename or 'skip')
-Approve? (yes/no/preview):
+Preview content? (type filename, 'all' for batch, or 'skip')
+Approve? [y/n/edit]: _
 ```
 
-**If user types filename**: Show first 30 lines of that file
+**If user types 'all'**: Show first 10 lines of each file in sequence
+**If user types filename**: Show full content of that file
+**If user types 'skip'**: Proceed to approval
 
 **Validation**: MUST get approval before proceeding
 
@@ -108,11 +134,11 @@ Approve? (yes/no/preview):
 
 ---
 
-### Stage 6: Update Navigation
-**Action**: Update README.md and add cross-references
+### Stage 6: Update Navigation (preview included in Stage 4)
+**Action**: Update navigation.md and add cross-references
 
 **Process**:
-1. Update category README.md with new files
+1. Update category navigation.md with new files (as previewed in Stage 4)
 2. Add priority levels (critical/high/medium/low)
 3. Add cross-references between related files
 4. Update "Last Updated" dates

.opencode/context/core/context-system/operations/harvest.md

@@ -160,27 +160,76 @@ Found 3 summary documents:
 1. For each approved item:
    - Extract core content
    - Apply MVI minimization (see compact.md)
-   - Add to target file (create if needed)
+   - Generate preview of final content
+2. Show extraction preview (APPROVAL REQUIRED):
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Extraction Preview
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[A] → core/concepts/context-organization.md (CREATE, 45 lines)
+┌─────────────────────────────────────────────────────────┐
+│ # Concept: Context Organization                         │
+│                                                         │
+│ **Purpose**: Function-based knowledge organization      │
+│                                                         │
+│ ## Core Concept                                         │
+│ Organize context by function: concepts/, examples/...   │
+│ ...                                                     │
+└─────────────────────────────────────────────────────────┘
+
+[E] → development/errors/auth-errors.md (ADD to existing, 98 → 112 lines)
+┌─────────────────────────────────────────────────────────┐
+│ + ## Error: JWT Token Expiration Not Handled             │
+│ +                                                       │
+│ + **Symptom**: 401 after 1 hour                         │
+│ + **Cause**: No refresh token flow                      │
+│ + ...                                                   │
+└─────────────────────────────────────────────────────────┘
+
+... ({remaining_count} more items)
+
+Show all? [y/n] | Approve extraction? [y/n/edit]: _
+```
+
+3. On approval:
+   - Write files to disk
    - Add cross-references
-   - Update related files
-2. Update navigation.md navigation maps
-3. Validate file sizes (<200 lines)
+   - Update navigation.md maps
 
 **Output**: List of created/updated files
 
 ---
 
-### Stage 5: Cleanup
+### Stage 5: Cleanup (APPROVAL REQUIRED)
 **Action**: Archive or delete source summary files
 
-**Default Strategy**: Archive (safe)
-- Move to `.tmp/archive/harvested/{date}/`
-- Preserves originals in case of mistakes
-- Can be safely deleted later
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Cleanup: Source Files
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Successfully harvested from:
+  CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB)
+  SESSION-auth-work.md (1.8 KB)
 
-**Alternative**: Delete (if user specified)
-- Permanently remove files
-- Only delete items user approved for harvest
+Skipped (no valuable content):
+  .tmp/IMPLEMENTATION-NOTES.md (800 bytes)
+
+How should we handle these source files?
+
+  1. Archive (safe) — move to .tmp/archive/harvested/{date}/
+     → Can restore later if needed
+
+  2. Delete — permanently remove harvested files
+     → Frees disk space, no undo
+
+  3. Keep — leave source files in place
+     → No cleanup, files remain where they are
+
+Choose [1/2/3] (default: 1): _
+```
 
 <rule id="cleanup_safety" enforcement="strict">
   ONLY cleanup files that had content successfully harvested.

.opencode/context/core/context-system/operations/migrate.md

@@ -0,0 +1,221 @@
+# Context Migrate Operation
+
+**Purpose**: Copy context files from global (`~/.config/opencode/context/`) to local (`.opencode/context/`) so they're project-specific and git-committed.
+
+**Last Updated**: 2026-02-06
+
+---
+
+## Core Problem
+
+Users who installed OAC globally have project-intelligence files at `~/.config/opencode/context/project-intelligence/`. These files are project-specific patterns but aren't committed to git or shared with the team.
+
+**Solution**: Migrate project-intelligence from global → local, so patterns are version-controlled and team-shared.
+
+---
+
+## 4-Stage Workflow
+
+<workflow id="migrate" enforce="@critical_rules">
+
+### Stage 1: Detect Sources
+
+Scan for context files in the global config directory:
+
+```
+Scanning global context...
+
+Global location: ~/.config/opencode/context/
+
+Found:
+  project-intelligence/
+    technical-domain.md (1.2 KB, Version: 1.3)
+    navigation.md (800 bytes, Version: 1.0)
+    business-domain.md (1.5 KB, Version: 1.1)
+
+Local location: .opencode/context/
+
+Status: No local project-intelligence/ found
+```
+
+**If no global context found:**
+```
+No global context found at ~/.config/opencode/context/
+
+Nothing to migrate. Use /add-context to create project intelligence.
+```
+→ Exit
+
+**If no global project-intelligence found (but other global context exists):**
+```
+Global context found at ~/.config/opencode/context/ but no project-intelligence/ directory.
+
+Only project-intelligence files are migrated (project-specific patterns).
+Core standards stay in global (they're universal, not project-specific).
+
+Nothing to migrate. Use /add-context to create project intelligence.
+```
+→ Exit
+
+---
+
+### Stage 2: Check for Conflicts
+
+If local `.opencode/context/project-intelligence/` already exists:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Conflict: Local project-intelligence already exists
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Global files:                              Local files:
+  technical-domain.md                        technical-domain.md
+    Version: 1.3, Updated: 2026-01-15         Version: 1.0, Updated: 2026-02-01
+  navigation.md                              navigation.md
+    Version: 1.0, Updated: 2026-01-10         Version: 1.0, Updated: 2026-02-01
+  business-domain.md                         (not present locally)
+    Version: 1.1, Updated: 2026-01-12
+
+Options:
+  1. Skip existing — only copy files that don't exist locally
+     → Will copy: business-domain.md
+     → Will skip: technical-domain.md, navigation.md (local kept)
+
+  2. Overwrite all — replace local with global versions
+     → Will overwrite: technical-domain.md, navigation.md
+     → Will copy: business-domain.md
+     → Local backup created first
+
+  3. Cancel
+
+Choose [1/2/3]: _
+```
+
+**If user chooses 2 (Overwrite), show content diff first:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Diff: technical-domain.md
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Local (current):                    Global (incoming):
+  Version: 1.0                        Version: 1.3
+  Tech Stack: Next.js 14              Tech Stack: Next.js 15  ← different
+  API: basic validation                API: Zod validation     ← different
+  Component: same                      Component: same
+  Naming: same                         Naming: same
+
+Show full diff? [y/n]: _
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Backup local files to .tmp/backup/migrate-{timestamp}/ before overwriting?
+[y/n] (default: y): _
+```
+
+If no conflicts → proceed directly to Stage 3.
+
+---
+
+### Stage 3: Approval & Copy
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Migration Plan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Will copy from: ~/.config/opencode/context/project-intelligence/
+Will copy to:   .opencode/context/project-intelligence/
+
+Files to copy:
+  ✓ technical-domain.md (1.2 KB)
+  ✓ navigation.md (800 bytes)
+  ✓ business-domain.md (1.5 KB)
+
+After migration:
+  → Local files committed to git = team gets your patterns
+  → Agents load local (overrides global)
+  → Global files remain as fallback for other projects
+
+Proceed? [y/n]: _
+```
+
+**Actions on approval:**
+1. Create `.opencode/context/project-intelligence/` if it doesn't exist
+2. Copy each file from global → local
+3. Validate copied files (frontmatter, MVI compliance)
+
+---
+
+### Stage 4: Cleanup & Confirmation
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Migration Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Copied 3 files to .opencode/context/project-intelligence/
+
+  ✓ technical-domain.md
+  ✓ navigation.md
+  ✓ business-domain.md
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Clean up global project-intelligence?
+
+The global files are no longer needed for THIS project (local takes priority).
+Keeping them means they still apply as fallback to other projects.
+
+  1. Keep global files (safe default)
+  2. Remove global project-intelligence/ (only affects this user)
+
+Choose [1/2] (default: 1): _
+```
+
+**If user chooses 2 (Remove):**
+- Delete `~/.config/opencode/context/project-intelligence/` only
+- Do NOT touch `~/.config/opencode/context/core/` or any other global context
+
+</workflow>
+
+---
+
+## What Gets Migrated
+
+| Migrated (project-specific) | NOT Migrated (universal) |
+|---|---|
+| `project-intelligence/` | `core/standards/` |
+| `project-intelligence/technical-domain.md` | `core/context-system/` |
+| `project-intelligence/business-domain.md` | `core/workflows/` |
+| `project-intelligence/navigation.md` | `core/guides/` |
+| `project-intelligence/decisions-log.md` | Any other `core/` files |
+| `project-intelligence/living-notes.md` | |
+
+**Rationale**: Project intelligence is project-specific (YOUR tech stack, YOUR patterns). Core standards are universal (code quality, documentation standards) and should stay global.
+
+---
+
+## Error Handling
+
+**Permission denied:**
+```
+Error: Cannot write to .opencode/context/project-intelligence/
+Check directory permissions and try again.
+```
+
+**Global path not found:**
+```
+No global OpenCode config found at ~/.config/opencode/
+
+If you installed to a custom location, set OPENCODE_INSTALL_DIR:
+  export OPENCODE_INSTALL_DIR=/your/custom/path
+  /context migrate
+```
+
+---
+
+## Related
+
+- `/add-context` — Create new project intelligence (interactive wizard)
+- `/context harvest` — Extract knowledge from summaries
+- Context path resolution: `.opencode/context/core/system/context-paths.md`

.opencode/context/core/system/context-paths.md

@@ -1,18 +1,83 @@
 ---
 id: context-paths
-name: Additional Context File Paths
+name: Context File Path Resolution
 ---
 
-# Additional Context File Paths
+# Context File Path Resolution
 
-Additional paths to context. If set to `false`, ignore.
+## Resolution Order
+
+Context files are resolved in this order (later sources override earlier ones for conflicting keys):
+
+1. **Global context** (`~/.config/opencode/context/`) — user-wide defaults
+2. **Local context** (`.opencode/context/` in project root) — project-specific, highest priority
+
+This mirrors OpenCode's own config merging behavior (see [OpenCode Config Docs](https://opencode.ai/docs/config/)).
+
+## 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
 
 ```json
 {
   "paths": {
     "local": ".opencode/context",
-    "global": false
+    "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:
+
+```bash
+export OPENCODE_INSTALL_DIR=~/custom/path
+bash install.sh developer
+```
+
+OpenCode itself supports `OPENCODE_CONFIG_DIR` for a custom config directory (see [OpenCode docs](https://opencode.ai/docs/config/)). 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:
+
+```bash
+/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`

CONTEXT_SYSTEM_GUIDE.md

@@ -60,11 +60,11 @@ Code matches your standards automatically
 **Step 2: ContextScout discovers**
 - `core/standards/code-quality.md` (modular patterns)
 - `ui/web/react-patterns.md` (React conventions)
-- `project/project-context.md` (YOUR patterns)
+- `project-intelligence/technical-domain.md` (YOUR patterns)
 
 **Step 3: Agent loads context**
 ```markdown
-# From project-context.md
+# From project-intelligence/technical-domain.md
 
 ## React Component Pattern
 
@@ -129,8 +129,10 @@ export const UserProfile: React.FC<UserProfileProps> = ({ user }) => {
 │   ├── ui-navigation.md
 │   └── [language-specific patterns]
 │
-└── project/                        # YOUR custom patterns
-    └── project-context.md          # Edit this file!
+└── project-intelligence/            # YOUR custom patterns
+    ├── technical-domain.md          # Tech stack & code patterns
+    ├── business-domain.md           # Business context
+    └── navigation.md                # Quick overview
 ```
 
 ---
@@ -204,8 +206,14 @@ const addToTotal = (value) => { total += value; };
 ### Step 1: Edit Your Project Context
 
 ```bash
-# Open your project context file
-nano ~/.opencode/context/project/project-context.md
+# Recommended: Use the interactive wizard
+/add-context
+
+# Or edit directly (local project install):
+nano .opencode/context/project-intelligence/technical-domain.md
+
+# Global install:
+# nano ~/.config/opencode/context/project-intelligence/technical-domain.md
 ```
 
 ### Step 2: Add Your Patterns
@@ -624,7 +632,7 @@ All API endpoints should be good
 ### 4. Update Regularly
 
 When you change patterns:
-1. Update `project-context.md`
+1. Run `/add-context --update` or edit `project-intelligence/technical-domain.md` directly
 2. Agents will use new patterns immediately
 3. No need to restart anything
 
@@ -635,7 +643,7 @@ When you change patterns:
 ### Problem: Agent isn't following my patterns
 
 **Solution**:
-1. Check that `project-context.md` exists
+1. Check that `project-intelligence/technical-domain.md` exists (run `/add-context` if not)
 2. Verify the pattern is clearly written
 3. Include a real example
 4. Ask agent to "follow project patterns"
@@ -643,7 +651,7 @@ When you change patterns:
 ### Problem: Agent uses old patterns
 
 **Solution**:
-1. Update `project-context.md`
+1. Run `/add-context --update` or edit `project-intelligence/technical-domain.md`
 2. Restart the agent
 3. Ask agent to "load latest context"
 
@@ -657,7 +665,7 @@ When you change patterns:
 ### Problem: Agent creates code that doesn't match
 
 **Solution**:
-1. Check if pattern is in `project-context.md`
+1. Check if pattern is in `project-intelligence/technical-domain.md`
 2. Verify pattern is specific enough
 3. Ask agent to "review against project patterns"
 4. Provide feedback to refine pattern
@@ -681,7 +689,7 @@ Agents load context in this order:
    - `ui/web/react-patterns.md`
 
 4. **Project-Specific** (YOUR patterns) ← Most important!
-   - `project/project-context.md`
+   - `project-intelligence/technical-domain.md`
 
 **Project context overrides everything else!**
 
@@ -698,8 +706,8 @@ Agents load context in this order:
 ✅ **Living documentation** - Patterns stay in sync with code
 
 **Get started**:
-1. Edit `~/.opencode/context/project/project-context.md`
-2. Add your patterns with examples
+1. Run `/add-context` to create project intelligence interactively
+2. Or edit `.opencode/context/project-intelligence/technical-domain.md` directly
 3. Ask agents to create code
 4. Watch them follow your patterns automatically!
 
@@ -707,10 +715,10 @@ Agents load context in this order:
 
 ## Next Steps
 
-1. **Review** your current coding patterns
-2. **Document** them in `project-context.md`
+1. **Run** `/add-context` to create project intelligence interactively
+2. **Review** your current coding patterns
 3. **Include** real examples from your project
 4. **Test** by asking agents to create code
-5. **Refine** patterns based on results
+5. **Refine** patterns with `/add-context --update`
 
 Your agents will become better and better as your context improves!

README.md

@@ -284,7 +284,8 @@ Before generating code, ContextScout discovers relevant patterns from your conte
 **2. Editable Agents - Full Control**  
 Unlike Cursor/Copilot where behavior is baked into plugins, AOC agents are markdown files. Edit them directly:
 ```bash
-nano ~/.opencode/agent/core/opencoder.md
+nano .opencode/agent/core/opencoder.md  # local project install
+# Or: nano ~/.config/opencode/agent/core/opencoder.md  # global install
 # Add project rules, change workflows, customize behavior
 ```
 
@@ -506,7 +507,8 @@ Approve? [y/n]
 
 Edit agent files directly:
 ```bash
-nano ~/.opencode/agent/core/opencoder.md
+nano .opencode/agent/core/opencoder.md  # local project install
+# Or: nano ~/.config/opencode/agent/core/opencoder.md  # global install
 ```
 
 Change the model in the frontmatter:
@@ -634,7 +636,7 @@ A: MVI principle: Only load what's needed, when it's needed. Context files <200
 A: Smart pattern discovery agent. Finds relevant context files before code generation. Ranks by priority. Prevents wasted work.
 
 **Q: Can I edit agent behavior?**  
-A: Yes! Agents are markdown files. Edit them directly: `nano ~/.opencode/agent/core/opencoder.md`
+A: Yes! Agents are markdown files. Edit them directly: `nano .opencode/agent/core/opencoder.md` (local) or `nano ~/.config/opencode/agent/core/opencoder.md` (global)
 
 **Q: How do approval gates work?**  
 A: Agents ALWAYS request approval before execution (write/edit/bash). You review plans before implementation. No surprises.
@@ -665,7 +667,7 @@ A: Bash 3.2+ (macOS default works). Run `bash scripts/tests/test-compatibility.s
 A: No, they're optional. Only install if you want Telegram notifications or Gemini AI features.
 
 **Q: Where should I install - globally or per-project?**  
-A: Global (`~/.opencode/`) works for most. Project-specific (`.opencode/`) if you need different configs per project.
+A: Local (`.opencode/` in your project) is recommended — patterns are committed to git and shared with your team. Global (`~/.config/opencode/`) is good for personal defaults across all projects. The installer asks you to choose. See [OpenCode Config Docs](https://opencode.ai/docs/config/) for how configs merge.
 
 ---
 

docs/getting-started/platform-compatibility.md

@@ -334,13 +334,19 @@ If you can't use the installer:
 git clone https://github.com/darrenhinde/OpenAgentsControl.git
 cd OpenAgentsControl
 
-# 2. Copy to OpenCode directory
-mkdir -p ~/.opencode
-cp -r .opencode/agent ~/.opencode/
-cp -r .opencode/command ~/.opencode/
-cp -r .opencode/context ~/.opencode/
-cp -r .opencode/tool ~/.opencode/
-cp -r .opencode/plugin ~/.opencode/
+# 2a. Install locally (recommended - in your project directory):
+bash install.sh developer
+
+# 2b. Or install globally (available to all projects):
+bash install.sh developer --install-dir ~/.config/opencode
+
+# 2c. Or copy manually to global location:
+mkdir -p ~/.config/opencode
+cp -r .opencode/agent ~/.config/opencode/
+cp -r .opencode/command ~/.config/opencode/
+cp -r .opencode/context ~/.config/opencode/
+cp -r .opencode/tool ~/.config/opencode/
+cp -r .opencode/plugin ~/.config/opencode/
 
 # 3. Configure environment
 cp env.example .env

registry.json

@@ -1227,6 +1227,16 @@
         "dependencies": [],
         "category": "standard"
       },
+      {
+        "id": "migrate",
+        "name": "Migrate",
+        "type": "context",
+        "path": ".opencode/context/core/context-system/operations/migrate.md",
+        "description": "Migrate context from global to local project",
+        "tags": [],
+        "dependencies": [],
+        "category": "standard"
+      },
       {
         "id": "organize",
         "name": "Organize",