# Config Module Usage Map

This document shows how each file uses the config module and what subpaths they access.

## Overview Diagram

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              config.ts exports                                   │
├─────────────────────────────────────────────────────────────────────────────────┤
│ Constants:        APP_NAME, CONFIG_DIR_NAME, VERSION                            │
│ Single paths:     getAgentDir, getAuthPath, getModelsPath, getModelsYamlPath,   │
│                   getAgentDbPath, getToolsDir, getCommandsDir, getPromptsDir,   │
│                   getSessionsDir, getDebugLogPath, getCustomThemesDir,          │
│                   getChangelogPath, getPackageDir                               │
│ Multi-config:     getConfigDirs, getConfigDirPaths, findConfigFile,             │
│                   findConfigFileWithMeta, readConfigFile, readAllConfigFiles,   │
│                   findNearestProjectConfigDir, findAllNearestProjectConfigDirs  │
└─────────────────────────────────────────────────────────────────────────────────┘
```

## Architecture Note

Many modules now use the **capability/discovery system** (`discovery/builtin.ts`) to load configuration files (skills, hooks, tools, MCP servers, etc.) rather than importing config helpers directly. The capability system provides a unified way to load resources from multiple sources (.omp, .pi, .claude, .codex, .gemini) with proper priority ordering.

## Usage by Category

### 1. Display/Branding Only (no file I/O)

| File                          | Imports                       | Purpose                  |
| ----------------------------- | ----------------------------- | ------------------------ |
| `cli/args.ts`                 | `APP_NAME`, `CONFIG_DIR_NAME` | Help text, env var names |
| `cli/grep-cli.ts`             | `APP_NAME`                    | Grep command output      |
| `cli/jupyter-cli.ts`          | `APP_NAME`                    | Jupyter command output   |
| `cli/plugin-cli.ts`           | `APP_NAME`                    | Plugin command output    |
| `cli/setup-cli.ts`            | `APP_NAME`                    | Setup command output     |
| `cli/shell-cli.ts`            | `APP_NAME`                    | Shell command output     |
| `cli/stats-cli.ts`            | `APP_NAME`                    | Stats command output     |
| `cli/update-cli.ts`           | `APP_NAME`, `VERSION`         | Update messages          |
| `cli.ts`                      | `APP_NAME`                    | Process title            |
| `export/html/index.ts`        | `APP_NAME`                    | HTML export title        |
| `modes/components/welcome.ts` | `APP_NAME`                    | Welcome banner           |
| `debug/system-info.ts`        | `VERSION`                     | System info display      |

### 2. Single Fixed Paths (user-level only)

| File                                       | Imports                            | Path                            | Purpose                 |
| ------------------------------------------ | ---------------------------------- | ------------------------------- | ----------------------- |
| `cli/config-cli.ts`                        | `APP_NAME`, `getAgentDir`          | `~/.omp/agent/`                 | Prints config path      |
| `session/agent-session.ts`                 | `getAgentDbPath`                   | `~/.omp/agent/agent.db`         | Database path           |
| `session/session-manager.ts`               | `getAgentDir`                      | `~/.omp/agent/sessions/`        | Session storage         |
| `session/agent-storage.ts`                 | `getAgentDbPath`                   | `~/.omp/agent/agent.db`         | Settings/auth storage   |
| `session/auth-storage.ts`                  | `getAgentDbPath`                   | agent.db                        | Auth credential storage |
| `session/history-storage.ts`               | `getAgentDir`                      | `~/.omp/agent/`                 | Command history         |
| `session/storage-migration.ts`             | `getAgentDbPath`                   | `~/.omp/agent/agent.db`         | JSON→SQLite migration   |
| `modes/theme/theme.ts`                     | `getCustomThemesDir`               | `~/.omp/agent/themes/`          | Custom themes           |
| `modes/controllers/selector-controller.ts` | `getAgentDbPath`                   | `~/.omp/agent/agent.db`         | Model selector state    |
| `utils/changelog.ts`                       | `getChangelogPath`                 | Package CHANGELOG.md            | Re-exports path         |
| `migrations.ts`                            | `getAgentDir`, `getAgentDbPath`    | `~/.omp/agent/`                 | Auth/session migration  |
| `extensibility/plugins/installer.ts`       | `getAgentDir`                      | `~/.omp/agent/plugins/`         | Plugin installation     |
| `extensibility/plugins/paths.ts`           | `CONFIG_DIR_NAME`                  | `~/.omp/plugins/`               | Plugin directories      |
| `config/keybindings.ts`                    | `getAgentDir`                      | `~/.omp/agent/keybindings.json` | Keybinding config       |
| `config/settings.ts`                       | `getAgentDir`, `getAgentDbPath`    | agent.db, config.yml            | Settings management     |
| `config/prompt-templates.ts`               | `CONFIG_DIR_NAME`, `getPromptsDir` | `~/.omp/agent/prompts/`         | Prompt template loading |
| `ipy/executor.ts`                          | `getAgentDir`                      | `~/.omp/agent/`                 | Python executor paths   |
| `ipy/gateway-coordinator.ts`               | `getAgentDir`                      | `~/.omp/agent/`                 | Jupyter gateway socket  |
| `export/custom-share.ts`                   | `getAgentDir`                      | `~/.omp/agent/share/`           | Custom share scripts    |
| `debug/index.ts`                           | `getSessionsDir`                   | `~/.omp/agent/sessions/`        | Debug session browser   |
| `ssh/connection-manager.ts`                | `CONFIG_DIR_NAME`                  | `~/.omp/ssh/`                   | SSH control sockets     |
| `ssh/sshfs-mount.ts`                       | `CONFIG_DIR_NAME`                  | `~/.omp/remote/`                | Remote mount points     |
| `tools/read.ts`                            | `CONFIG_DIR_NAME`                  | Config dir name reference       | Internal URL resolution |
| `utils/tools-manager.ts`                   | `APP_NAME`, `getToolsDir`          | `~/.omp/agent/tools/`           | Tool binary management  |

### 3. Multi-Config Discovery (with fallbacks)

These use helpers to check `.omp`, `.pi`, `.claude`, `.codex`, `.gemini` directories:

| File                                      | Helper Used                                        | Subpath(s)                      | Levels       |
| ----------------------------------------- | -------------------------------------------------- | ------------------------------- | ------------ |
| `main.ts`                                 | `findConfigFile`                                   | `SYSTEM.md`, `APPEND_SYSTEM.md` | user+project |
| `sdk.ts`                                  | `getConfigDirPaths`                                | `models.yml`, `models.json`     | user         |
| `lsp/config.ts`                           | `getConfigDirPaths`                                | `lsp.json`, `.lsp.json`         | user+project |
| `task/discovery.ts`                       | `getConfigDirs`, `findAllNearestProjectConfigDirs` | `agents/`                       | user+project |
| `extensibility/plugins/paths.ts`          | `getConfigDirPaths`                                | `plugin-overrides.json`         | project      |
| `extensibility/custom-commands/loader.ts` | `getConfigDirs`                                    | `commands/`                     | user+project |
| `web/search/auth.ts`                      | `getConfigDirPaths`, `getAgentDbPath`              | agent.db                        | user         |
| `web/search/providers/codex.ts`           | `getConfigDirPaths`, `getAgentDbPath`              | auth config                     | user         |
| `web/search/providers/gemini.ts`          | `getConfigDirPaths`, `getAgentDbPath`              | auth config                     | user         |

### 4. Via Capability/Discovery System

These modules use `discovery/builtin.ts` which has its own config directory resolution:

| Capability     | Config Subpaths             | Loaded Via               |
| -------------- | --------------------------- | ------------------------ |
| skills         | `skills/`                   | `skillCapability`        |
| slash-commands | `commands/`                 | `slashCommandCapability` |
| rules          | `rules/`                    | `ruleCapability`         |
| prompts        | `prompts/`                  | `promptCapability`       |
| instructions   | `instructions/`             | `instructionCapability`  |
| hooks          | `hooks/pre/`, `hooks/post/` | `hookCapability`         |
| tools          | `tools/`                    | `toolCapability`         |
| extensions     | `extensions/`               | `extensionCapability`    |
| mcp            | `mcp.json`, `.mcp.json`     | `mcpCapability`          |
| settings       | `settings.json`             | `settingsCapability`     |
| system-prompt  | `SYSTEM.md`                 | `systemPromptCapability` |

## Subpath Summary

```
User-level (~/.omp/agent/, ~/.pi/agent/, ~/.claude/, ~/.codex/, ~/.gemini/):
├── agent.db           ← SQLite storage (settings, auth)
├── models.yml         ← Model configuration (preferred)
├── models.json        ← Model configuration (legacy)
├── config.yml         ← Settings (alternative to agent.db)
├── keybindings.json   ← Custom keybindings
├── commands/          ← Slash commands (via capability)
├── hooks/             ← Pre/post hooks (via capability)
│   ├── pre/
│   └── post/
├── tools/             ← Custom tools (via capability)
├── skills/            ← Skills (via capability)
├── prompts/           ← Prompt templates
├── themes/            ← Custom themes
├── sessions/          ← Session storage
├── agents/            ← Custom task agents
├── plugins/           ← Installed plugins
├── extensions/        ← Extension modules
├── rules/             ← Rules (via capability)
├── instructions/      ← Instructions (via capability)
├── share/             ← Custom share scripts
└── AGENTS.md          ← User-level agent instructions

User-level root (~/.omp/, ~/.pi/, ~/.claude/) - not under agent/:
├── mcp.json           ← MCP server config (via capability)
├── plugins/           ← Plugin storage (primary only)
├── logs/              ← Log files (primary only, via pi-utils)
├── ssh/               ← SSH control sockets
└── remote/            ← SSHFS mount points

Project-level (.omp/, .claude/, .codex/, .gemini/):
├── SYSTEM.md          ← Project system prompt
├── APPEND_SYSTEM.md   ← Appended to system prompt
├── settings.json      ← Project settings (via capability)
├── commands/          ← Slash commands (via capability)
├── hooks/             ← Pre/post hooks (via capability)
├── tools/             ← Custom tools (via capability)
├── skills/            ← Skills (via capability)
├── agents/            ← Custom task agents
├── extensions/        ← Extension modules (via capability)
├── rules/             ← Rules (via capability)
├── instructions/      ← Instructions (via capability)
├── prompts/           ← Prompt templates (via capability)
├── plugin-overrides.json ← Plugin config overrides
├── lsp.json           ← LSP server config
├── .lsp.json          ← LSP server config (dotfile)
└── .mcp.json          ← MCP server config (via capability)
```

## Notes

### Logger

Logging is handled by `@oh-my-pi/pi-utils`, not by this package. Logs go to `~/.omp/logs/omp.YYYY-MM-DD.log` with automatic rotation.

### Config Priority

When multiple config directories exist, priority order is:

1. `.omp` (highest)
2. `.pi`
3. `.claude`
4. `.codex`
5. `.gemini` (lowest)

For user-level paths, `.omp/agent` and `.pi/agent` have an "agent" subdirectory; others use the root directly (e.g., `~/.claude/` not `~/.claude/agent/`).
