nacre: Skill for Claude Code

Adding configuration

Contract: docs/config.md.

Rules

1. Prefix NACRE_. No exceptions, including in the parser sidecar.
2. Validate the whole configuration at startup and exit if anything required is missing or contradictory. Not on first use — at boot.
3. No silent defaults for secrets or URLs. A default that quietly points at localhost is how a production deployment talks to nothing and reports success. Defaults are fine for tunables (NACRE_ACL_CACHE_TTL=60); they are not fine for anything naming a host or carrying a credential.
4. Secrets are references into a secret store where the platform allows it — NACRE_JWT_PRIVATE_KEY_REF=file:///run/secrets/…, not the key itself. Plaintext values are for the development profile and nowhere else.

Every new variable touches four places

• the implementation's startup validation
• .env.example — development values only, never a real credential
• docs/config.md
• the Compose profile, if a service reads it

A variable that exists in code but not in docs/config.md is invisible to the person deploying this, which for a self-hosted product is the person who matters most.

And the four have to agree, not merely all exist. lint:config checks existence and that is not the same thing. NACRE_MCP_CANONICAL_URL was present in all four and they contradicted each other: docker-compose.yml omitted it from the mcp service with eleven lines explaining that its absence was the fix, and .env.example seeded it — and env_file sits on the shared service anchor, so the value reached the container anyway. Every deployment that started from cp .env.example .env had the fix silently undone.

So before adding a line to .env.example, ask what happens when a service deliberately does not set that variable. If the answer is "the seeded value wins", the variable belongs commented out with the reason, and the reason belongs in lint:compose rather than only in a comment — a comment does not travel to the next file.