# OpenCode Configuration - Agent Reference

## Configuration Structure

This directory contains OpenCode configuration managed via nix-darwin.

### Nix-Managed (Read-Only Symlinks)

- `opencode.jsonc` - Main configuration
- `AGENTS.md` - This file (directory agent instructions)
- `GLOBAL_INSTRUCTIONS.md` - Global agent instructions
- `rules/` - Rule files (shell-strategy, etc.)
- `command/` - Slash commands
- `skills/` - Agent skills
- `agent/` - Custom agent definitions

### Nix-Managed (Copied via Activation Script)

- `tool/` - Custom tools (copied so bun can resolve node_modules)
- `package.json` - Dependencies for tools/plugins
- `node_modules/` - Installed via bun install in activation script

### User-Managed (NOT in Nix)

- `plugin/` - Directory for user-managed plugins

## Plugin Management

**User-managed plugins:**

- Clone to `~/.config/opencode/plugin/`
- For TypeScript plugins: run `bun run build`
- Add to `opencode.jsonc` `plugins` array: `"./plugin/<plugin-name>"`

**Required user-managed plugins:**

- `opencode-jj` - https://github.com/edmundmiller/opencode-jj (TypeScript, needs build)
- `boomerang-notify` - https://github.com/edmundmiller/boomerang-notify

**Important:** Local plugins must be explicitly registered in `opencode.jsonc` `plugins` array.

## Rebuild Workflow

After `hey rebuild`:

- Symlinked files update automatically
- `tool/` directory re-syncs
- `bun install` runs for dependencies
- User-managed plugins are UNTOUCHED

## Modifying Configuration

To modify nix-managed files:

1. Edit in `~/.config/dotfiles/config/opencode/`
2. Run `hey rebuild`
3. Changes take effect immediately
