kavo: Skill for Claude Code

Adding a config key

Kavo has one configuration mechanism: KavoSettings, merged through a single precedence chain (docs/internals/architecture/08-configuration.md):

built-in defaults → global (createKavo) → entity (createCrud)
                  → operation (operations.<id>) → per-call (KavoCallOptions)

The schema-extensibility rule (doc 08 §1) is normative: feature work adds keys to this schema — it never adds a second config mechanism. If you find yourself threading a new constructor parameter or a separate options object through the engine, stop; it belongs in KavoSettings.

Where the pieces live

1. BUILT_IN_DEFAULTS (packages/core/src/config/defaults.ts) — add the key with its default value. Every key needs one; there is no "unset" state a resolved config can observe.
2. The settings type — extend the KavoSettings interface/schema so the new key is typed at every scope (global defaults, entity config, operations.<id> overrides, KavoCallOptions.settings).
3. mergeSettings (packages/core/src/config/merge-settings.ts) — confirm the new key's shape matches the existing merge semantics rather than inventing a new one:
   • scalars and object-as-value keys: nearer scope replaces farther scope, key by key;
   • false disables an inheritable feature where the schema allows it (follow the delete / operations.<id> pattern) — a nearer object re-enables it;
   • arrays replace wholesale, never merge element-wise;
   • undefined at any scope is skipped, not treated as an explicit override.
4. validateSettings — add bootstrap validation that fails with a ConfigurationException naming the entity, the key path, and the offending value (doc 08 §4's message shape is the bar: Invalid configuration for entity 'User' at 'pagination.maxLimit': ...). Validation runs once at bootstrap (resolveEntityConfig), not per request — the resolved config is deep-frozen afterward, so this is the only chance to catch a bad value before it's baked in.
5. describeResolvedConfig — check whether the new key should surface in kavo.describe(entityName)'s debug dump; most settings keys should.