# Kuan Yin — Configuration

> Technical doc 32.16.1.9. Schema in `@kuanyin/foundation/env-schema.ts`
> (`validateKuanYinEnv`); tunable constants in `foundation/constants.ts`.

Configuration comes from two sources: **environment variables** (secrets,
endpoints, toggles), validated at boot, and **domain constants** (thresholds,
timings, weights) that ship with the foundation library and can be overridden
per community via the `MindfulFrictionConfig` / `PerformerProtectionConfig`
tables.

## Environment schema

`validateKuanYinEnv(env)` parses and validates the process environment with Zod
and returns a typed config object (or throws with the full issue list). It
covers database URLs, Redis, the event-bus/queue endpoint, model-serving
endpoints, third-party hash services (StopNCII, PhotoDNA), crisis-helpline
registries, and feature toggles. Call it once at startup and fail fast.

```ts
import { validateKuanYinEnv } from '@kuanyin/foundation';
const config = validateKuanYinEnv(process.env); // throws on missing/invalid
```

## Tunable domain constants

`foundation/constants.ts` defines the defaults that shape behaviour:

- Harm category thresholds and intervention timing.
- Merit point values, tier-unlock thresholds, karma decay rates, streak bonuses.
- Rehabilitation journey durations and shadow-work checkpoint intervals.
- Performer protection levels and mindful-friction timing.
- Trust score weights, community-health thresholds, escalation triggers.
- Cooldown periods, appeal windows, max consecutive violations, community-
  service hour requirements.

These are conservative, research-grounded starting points. Override per
community through the config tables rather than forking the constants, so the
defaults remain a safe baseline.

## Per-community overrides

`MindfulFrictionConfig` and `PerformerProtectionConfig` rows let a community
tune which gates apply, gate copy/localization, protection tiers, trusted-viewer
fast-tracking, and boundary templates without code changes. Resolve effective
config as `community override ?? foundation default`.

## Secrets

Secrets (DB credentials, hash-service keys, model tokens, webhook signing keys)
are never read from constants — only from the validated environment, sourced
from the platform secrets manager. Rotate signing keys on the schedule in
`12-security.md`.
