Three-tier plugin registration system is undocumented — agents cannot decide where to place code

[ooloth]

Why

An agent adding a general plugin will not know whether to create a spec file and require it or add it to languages.lua, and both mistakes silently fail or create duplicate loads.

Current state

The repo has three distinct places to add plugin configuration: category files (lua/config/plugins/*.lua), spec files (lua/config/plugins/specs/*.lua), and lang files (lua/config/plugins/lang/*.lua). These have critically different loading mechanisms: lang files are auto-loaded by require_all_files_in_config_directory, general spec files require explicit require() calls in a category file, and languages.lua itself is the auto-loader (not a file to add require lines to). None of this is documented in CLAUDE.md or any playbook.

Ideal state

• CLAUDE.md explicitly states that lang/ files are auto-loaded by languages.lua via require_all_files_in_config_directory and must never be manually required
• CLAUDE.md states that languages.lua is the loader, not a category file that accepts new require lines
• CLAUDE.md states that general plugin specs belong in specs/ and must be explicitly required from an appropriate category file
• The existing playbook at docs/playbooks/add-new-plugin.md reflects these distinctions

Out of scope

Changing the three-tier structure itself — this issue is documentation only.

Starting points

• lua/config/plugins/specs/ — browse to understand what a general spec file looks like
• lua/config/plugins/lang/ — browse to understand what a lang file looks like and how it differs
• docs/playbooks/add-new-plugin.md — the existing playbook that should be updated

QA plan

1. Read CLAUDE.md and identify where to place a new general plugin (e.g., a new UI plugin). Expect the documentation to direct you to specs/ and instruct you to add a require in the appropriate category file.
2. Read CLAUDE.md and identify where to place a new language support file (e.g., kotlin.lua). Expect the documentation to direct you to lang/ and state that no manual require is needed.
3. Verify that CLAUDE.md explicitly warns against adding require lines to languages.lua. Expect a clear statement that languages.lua is an auto-loader, not a category file.

Done when

CLAUDE.md explains all three registration locations and their loading mechanisms clearly enough that an agent can place a new plugin correctly on the first attempt without reading source files.