# Saeeol Rules Migration

This document explains how Saeeol rules are automatically migrated to Opencode's `instructions` config array.

## Overview

Saeeol stores rules in various file locations. When Opencode starts, it reads these files and injects their paths into the `instructions` config array, which Opencode then loads as part of the system prompt.

## Key Guarantees

### 1. Read-Only Migration

The migration **never modifies project files**. We only:

- Read existing rule files from disk
- Inject file paths into the config's `instructions` array
- Never write to the project or modify any files

### 2. Combines with Existing Config (Never Overwrites)

If you have existing saeeol config with `instructions`, the Saeeol rules are **combined**, not replaced:

```typescript
// Example: User has saeeol.json with:
{ "instructions": ["AGENTS.md", "custom-rules.md"] }

// Saeeol rules add:
{ "instructions": [".saeeolrules", ".saeeol/rules/coding.md"] }

// Result (combined, deduplicated):
{ "instructions": ["AGENTS.md", "custom-rules.md", ".saeeolrules", ".saeeol/rules/coding.md"] }
```

### 3. Restart to Pick Up Changes

If you change your Saeeol configuration (e.g., edit `.saeeolrules`), simply restart saeeol-cli to pick up the new config. No manual migration or conversion needed.

## Source Locations

The migrator reads rules from these locations:

### Project Rules

| Location | Description |
|---|---|
| `.saeeolrules` | Legacy single-file rules in project root |
| `.saeeol/rules/*.md` | Directory-based rules (multiple markdown files) |
| `.saeeolrules-{mode}` | Mode-specific legacy rules (e.g., `.saeeolrules-code`) |
| `.saeeol/rules-{mode}/*.md` | Mode-specific rule directories |

### Global Rules

| Location | Description |
|---|---|
| `~/.saeeol/rules/*.md` | Global rules directory |

## File Mapping

| Saeeol Location | Opencode Equivalent |
|---|---|
| `.saeeolrules` | `instructions: [".saeeolrules"]` |
| `.saeeolrules-{mode}` | `instructions: [".saeeolrules-{mode}"]` |
| `.saeeol/rules/*.md` | `instructions: [".saeeol/rules/file.md", ...]` |
| `.saeeol/rules-{mode}/*.md` | `instructions: [".saeeol/rules-{mode}/file.md", ...]` |
| `~/.saeeol/rules/*.md` | `instructions: ["~/.saeeol/rules/file.md", ...]` |

## AGENTS.md Compatibility

`AGENTS.md` is loaded **natively** by Opencode - no migration needed. Opencode automatically loads:

- `AGENTS.md` in project root
- `CLAUDE.md` in project root
- `~/.saeeol/AGENTS.md` (global)

## Not Migrated

The following are **not** migrated:

- `.roorules` - Roo-specific rules
- `.clinerules` - Cline-specific rules

Only Saeeol-specific files (`.saeeolrules`, `.saeeol/rules/`) are migrated.

## Mode-Specific Rules

Mode-specific rules (e.g., `.saeeolrules-code`, `.saeeol/rules-architect/`) are included by default. All mode-specific rules are loaded regardless of the current mode.

## Warnings

The migrator generates warnings for:

- **Legacy files**: When `.saeeolrules` is found, a warning suggests migrating to `.saeeol/rules/` directory structure

## Example

### Before (Saeeol)

```
project/
├── .saeeolrules           # Legacy rules
├── .saeeolrules-code      # Code-mode specific
└── .saeeol/
    └── rules/
        ├── coding.md        # Coding standards
        └── testing.md       # Testing guidelines
```

### After (Opencode Config)

```json
{
  "instructions": [
    "/path/to/project/.saeeol/rules/coding.md",
    "/path/to/project/.saeeol/rules/testing.md",
    "/path/to/project/.saeeolrules",
    "/path/to/project/.saeeolrules-code"
  ]
}
```

## Troubleshooting

### Rules not appearing

1. Check the file exists at the expected location
2. Ensure markdown files have `.md` extension
3. Restart saeeol-cli to pick up changes

### Duplicate rules

The `mergeConfigConcatArrays` function automatically deduplicates the `instructions` array using `Array.from(new Set([...]))`.

## Related Files

- [`rules-migrator.ts`](../rules-migrator.ts) - Core migration logic
- [`config-injector.ts`](../config-injector.ts) - Config building and injection
- [`modes-migration.md`](./modes-migration.md) - Modes migration documentation
