OpenAgentsControl/docs/maintenance/CONTEXTSCOUT_FIX.md

ContextScout Fix - Critical Files Missing from Installer

Problem

After running the installer, ContextScout fails with errors like:

• "Cannot locate context root"
• "Cannot discover context"
• "paths.json not found"

Root Cause

Two CRITICAL files required by ContextScout were NOT included in the registry:

1. paths.json (.opencode/context/core/config/paths.json)

   • Defines the context root location
   • Loaded via @ reference by agents on startup
   • Without it: ContextScout doesn't know where to look for context

2. navigation.md (.opencode/context/navigation.md)

   • Root navigation file for context discovery
   • ContextScout starts discovery HERE
   • Without it: ContextScout has no entry point for discovery

Solution

1. Added Critical Files to Registry

Created two new registry entries in registry.json:

{
  "id": "context-paths-config",
  "name": "Context Paths Configuration",
  "type": "context",
  "path": ".opencode/context/core/config/paths.json",
  "description": "CRITICAL: Context root path configuration - loaded via @ reference by agents",
  "tags": ["config", "paths", "critical", "context-system"],
  "dependencies": [],
  "category": "essential"
},
{
  "id": "root-navigation",
  "name": "Root Navigation",
  "type": "context",
  "path": ".opencode/context/navigation.md",
  "description": "CRITICAL: Root navigation file for context discovery - ContextScout starts here",
  "tags": ["navigation", "root", "critical", "context-system"],
  "dependencies": [],
  "category": "essential"
}

2. Added to All Profiles

Updated all 5 profiles to include these critical files:

• essential
• developer
• business
• full
• advanced

3. Added ContextScout Dependencies

Updated ContextScout's dependencies to explicitly require these files:

"dependencies": [
  "command:check-context-deps",
  "context:registry-dependencies",
  "context:context-system",
  "context:mvi",
  "context:structure",
  "context:workflows",
  "subagent:externalscout",
  "context:root-navigation",
  "context:context-paths-config"
]

Files Modified

Registry & Configuration

• registry.json - Added 2 critical context entries, updated ContextScout dependencies

Profiles

• .opencode/profiles/essential/profile.json - Added critical files
• .opencode/profiles/developer/profile.json - Added critical files
• .opencode/profiles/business/profile.json - Added critical files
• .opencode/profiles/full/profile.json - Added critical files
• .opencode/profiles/advanced/profile.json - Added critical files

Validation Results

Registry Validator:
✓ Total paths checked:    244
✓ Valid paths:            244
✓ Missing paths:          0
✓ Missing dependencies:   0

Installer File Test:
✓ All files accessible
✓ 0 files would fail

Testing After Fix

1. Run the installer:

   curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s essential
   

2. ContextScout should now work without errors:

   opencode
   # Then ask ContextScout to discover context
   

3. Verify files were installed:

   ls -la .opencode/context/navigation.md
   ls -la .opencode/context/core/config/paths.json
   

Why This Happened

The installer uses registry.json to determine which files to download. If a file isn't listed in the registry, it won't be installed.

These two files were essential infrastructure files that were:

• Referenced by agent code
• Required for ContextScout operation
• Present in the repository
• BUT not included in registry.json

Prevention

To prevent this in the future:

1. Always run registry validation before committing:

   bun run scripts/registry/validate-registry.ts
   

2. Test the installer after registry changes:

   ./scripts/tests/test-installer-files.sh --local --profile=essential
   

3. When adding new critical infrastructure files:

   • Add them to registry.json
   • Include them in all relevant profiles
   • Add as dependencies to components that require them

Related Documentation

• See .opencode/agent/subagents/core/contextscout.md for ContextScout requirements
• See .opencode/context/core/config/paths.json for context path configuration
• See .opencode/context/navigation.md for root navigation structure