Skip to content

y3owk1n/neru / .agents/skills/neru-add-config-option

neru-add-config-option

Verified

Add or change a Neru config.toml option end to end: struct field, shared and platform defaults, validation, examples, docs, and hot-reload behavior. Use whenever a change adds, renames, or removes a key in the TOML config schema. Not for theme palette entries or CLI flags.

FileKindSize
SKILL.mdskill md6.2 KB
agents/openai.yamlconfig277 B
---
name: neru-add-config-option
description: "Add or change a Neru config.toml option end to end: struct field, shared and platform defaults, validation, examples, docs, and hot-reload behavior. Use whenever a change adds, renames, or removes a key in the TOML config schema. Not for theme palette entries or CLI flags."
---

# Adding a config option to Neru

Config changes fail in review when one link of the chain is missing, such as a default
that exists on macOS but not Linux, a validator that never runs, or an example
file that still shows the old key. `internal/config/AGENTS.md` states the
contract and which test fails per link. This skill gives the order to do it in.

Five steps are universal. Then check the conditional four, the ones that turn
a one-line option into a ten-file one, and that no guide used to name.

## The universal five

1. **Schema.** Add the struct field in `internal/config/config.go` with a
   `toml:"snake_case_name"` tag matching the surrounding section. Follow the
   existing nesting. Options live in their feature's sub-struct, not at root.
   Then run `just genschema`, which renders the field into
   `schemas/config.schema.json` for editors.
   `TestConfigSchema_IsGeneratedFromTheConfigStructs` fails until you do.
2. **Shared default.** Set it in `newDefaultConfig()` in
   `internal/config/config_defaults.go`. Assign the field by name even when the
   value you assign is the zero value, and say in a comment what the zero
   means, because a zero nobody wrote cannot be told from a forgotten one.
   `TestEverySchemaFieldHasAnExplicitDefault` fails on an omission.
3. **Example.** Add the line to `configs/default-config.toml`, which is the file
   a user copies. Comment it out if the option has no default, because an uncommented
   empty value asserts a default that does not exist.
   `TestConfigOptionsAppearInTheDefaultExample` fails when the line is missing.
   Update the mode-specific examples (`grid-only-config.toml`,
   `hints-only-config.toml`, `recursive-grid-only-config.toml`) only if they
   show the affected section. They are deliberately partial, and only their
   *keys* are checked, by `TestRender_AcceptsEveryShippedExample`. Those four
   are the whole shipped set. `configs/embed.go` lists them, and anything else
   in `configs/` is a working file rather than a project artifact. Only
   `default-config.toml` is embedded, and the rest are read from disk by the tests
   that check them.
4. **Docs.** Add the row to `docs/reference/configuration.md`. That file is the single
   home for config reference facts. Do not also describe the option in
   `docs/contributing/architecture.md` or README. **No test catches a missing row.** This is the one
   universal link a reviewer has to check by eye.
5. **Platform column.** Add the option's path to `PlatformSupport()` in
   `internal/config/platform_support.go`, saying which of macOS, Linux and
   Windows writing it actually does something on. Say so even when the answer
   is all three, because a column nobody wrote cannot be told from a forgotten one, and
   `TestEveryConfigOptionDeclaresItsPlatformSupport` fails on an option that is
   neither. A narrower column needs a note saying why, in the words the user
   reads, because it reaches the load-time warning, the `neru doctor`
   `platform_support` row and the published table, which you regenerate with
   `just gensupportref`. A `config.Color` is declared at the field, not at its
   `light` and `dark` leaves
   (`docs/adr/0013-parity-is-measured-in-words-not-subsystems.md`).

Steps 2 and 3 exempt three shapes, and an option with one of them passes both
tests whether or not you do the work: the `light`/`dark` leaves under a `Color`,
a collection that ships empty, and any field of a repeated table nobody ships
entries for (`app_configs`, `layers`). Do the work anyway. See
`internal/config/AGENTS.md`.

## The conditional four

Each is skippable, and each is a whole file when it is not.

- **Platform override.** If a platform needs a different default, set it in
  `applyPlatformDefaults()` in the matching `config_<os>.go`
  (`config_darwin.go`, `config_linux.go`, `config_windows.go`,
  `config_other.go`). Both layers are reached via `DefaultConfig()` in
  `config_platform.go`, so never call `newDefaultConfig()` directly from feature
  code. Nothing checks this, so pin the difference in a test.
- **Validator.** Add checks to the relevant `Validate*` method on `*Config` in
  `internal/config/validators_*.go` (hints, grid, style, hotkeys, macros,
  pointer, appconfig, …). Invalid values must fail validation with a clear
  message, not get silently clamped. New enum-ish strings get an allowlist. A
  brand-new `Validate*` method must be called from `ValidateWithWarnings` in
  `validate.go`, or `TestEveryConfigValidatorRunsInTheLadder` fails.
- **Derivation helper.** If the value the daemon runs on is not the value the
  user writes, resolve it once after the configuration is assembled rather than
  in each consumer. `internal/config/grid_labels.go` and `held_repeat.go` are
  the worked examples. The declared default stays what a user would type.
- **Cross-field rule.** If the option only makes sense alongside another, and a
  user could act on the mismatch, collect it into `Warnings` so it rides out on
  `LoadResult` and reaches `neru config validate`. `logger.Warn` reaches nobody
  (ADR 0002, `docs/adr/0002-severity-tiered-config-validation.md`).

## Hot reload

Config is hot-reloadable via `internal/config/loader` (load/watch/persist/
set-field). If the option should be settable at runtime with `neru config set`,
confirm the field path resolves through the loader's set-field lookup. If it
intentionally requires a restart, say so in the docs.

## Tests

- Table-driven validator tests next to the validator you touched
  (`validators_*_test.go`), covering the default, a valid custom value, and at
  least one rejected value.
- If the default differs per platform, pin it in `config_defaults_test.go` or
  the platform-tagged config test.

## Verify

```bash
just test-foundation    # the fast cross-platform-safe slice
```

That one recipe now runs every package this skill's guardrails live in: the
config package, its loader, and `internal/architecture`.

Then the standard pre-commit gate from AGENTS.md.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall