# Writing an assessment config for the Relationships & Family engine

Each assessment is ONE JavaScript file that calls `FAM.register({...})`. The engine (`engine/core.js`) does every
screen, the scoring, patterns, report, PDF, history and couples comparison. You write data only — no code beyond
the object literal. **`assessments/relationships/relationship-communication.js` is the finished exemplar. Match
its depth, tone and structure exactly.** Read it first, top to bottom.

## Voice and rules (non-negotiable)

- Warm, plain, specific, adult. 10th–12th grade reading level. Short sentences. No jargon, no therapy-speak.
- Inclusive: partner / spouse / relationship / significant other / parent / caregiver / child / co-parent. Never
  assume husband+wife, male+female, married, or biological parents. (Fatherhood may say "father"; Motherhood may
  say "mother" — the person chose that assessment.)
- NOT clinical. Never diagnose or label (no attachment disorder, narcissism, depression, anxiety, PTSD, addiction,
  abuse, mental illness). Write tendencies: "You may tend to create distance when conflict intensifies."
- Lower scores are never "bad". They are growth opportunities. Never shame.
- Every piece of advice must be concrete and doable this week: a sentence to say, a thing to do, a rule to keep.
  Never "work on listening". Always "Before you reply, summarize their point and ask: Did I get that right?"
- "Me, not my partner": questions describe the taker's own behaviour. Never "My partner doesn't appreciate me."
- No periods at the end of titles/names. Headlines never end with a period.
- Use `{name}` (taker's first name), `{partner}` ("your partner"), `{child}` (child's name or "your child") in
  text; the engine fills them. Questions can use `{child}` and `{partner}` ("my partner").
- No copyrighted frameworks (no "love languages" wording or its five categories as a set).

## Required fields

```js
FAM.register({
  slug: 'kebab-case', version: '1',
  name: 'Title Case Name', group: 'couples' | 'parenting', icon: 'talk|repair|heart|scale|shield|star|users|child|home|sun',
  color: '#hex', minutes: '7–9',
  short: 'one sentence for the card',
  about: 'two or three sentences shown on the intro — what you will discover',
  reveals: ['4 bullets: what the report will reveal'],
  roles: ['Husband','Wife','Partner','Spouse','Other / prefer not to say']   // or parent roles: Father, Mother, Parent, Stepparent, Guardian, Caregiver, Other / prefer not to say
  context: [ { id, label, options:[...] } ],   // 3–5 optional questions that actually change the report
  dims: [ ...8–14 dimensions, see below ],
  items: [ ...35–55 questions, see below ],
  profiles / stressProfiles (optional, see exemplar), patterns (6–10), triggers (8–10), starters (6–8), reflection (5),
  summaries (3 rules), plan: { byDim: { every dim: { priority, weeks:[4] } }, byAge?: {...} },
  compare: { gapText: { dimId: text with {hi} {lo} {dim} }, starters: [3] }   // couples assessments only
  features: { ... }  // see per-assessment notes
});
```

### Dimensions
```js
{ id: 'snake_or_camel', name: 'Human Name', tag: 'one-line definition', ask: 'one conversation-starter question about this dim (couples assessments)',
  levels: { high: {...}, mid: {...}, low: {...} } }
```
`high` = score 70–100, `mid` = 55–69, `low` = 0–54. Every level has ALL of: `means` (2 sentences: what this means),
`everyday` (what it looks like in everyday life, 1–2 sentences, concrete), `others` (how the partner/child may
experience it), `blind` (potential blind spot), `action` (ONE recommended action, specific), `tryTitle` (short
imperative title) and `steps` (3–5 numbered, concrete steps for the "Try this" card). High levels still get a
real blind spot and a real action (strengths have shadows).

### Questions (items)
```js
{ id: 'xx01', dim: 'dimId', text: '...' }                         // likert: Strongly disagree … Strongly agree
{ id: 'xx02', dim: 'dimId', text: '...', reverse: true }          // reverse-scored
{ id: 'xx03', dim: 'dimId', text: '...', type: 'freq' }           // Rarely … Almost always (frequency wording)
{ id: 'xx04', dim: 'dimId', type: 'choice', fixed: true, text: 'When … I tend to…',
  options: [ { t: 'option text', s: { dimId: 1-5, otherDim: 1-5 }, tag: 'word' }, ... 5–7 options ] }   // situational
```
Per dimension: 4–6 items, at least one reverse-scored, at least one `freq`. 3–5 situational `choice` items per
assessment (`fixed: true` spreads them through the run). `tag`s feed patterns via `tag_<word>` (count of times
chosen). Questions must not make the desirable answer obvious; mix positive, reverse, frequency, behavioural,
preference. No two questions worded alike. Facets: `facet: 'give' | 'receive' | 'over' | 'under'` (see notes).

### Rules (`when` expressions)
Plain comparisons on dimension ids, `overall`, `tag_<word>`, `give_<dim>`, `receive_<dim>`, `over_<dim>`,
`under_<dim>`, `ctx_<contextId>` (string, compare with `== 'Yes'`), `age` (child age number), `rank_<dim>`
(1 = highest): e.g. `listening > 70 && expression < 55`, `tag_withdraw >= 1`, `age <= 5`.
`fit` expressions (profiles) are arithmetic on the same names and rank profiles (highest wins).
`excl: ['otherProfileId']` stops a contradictory secondary.

### Patterns
```js
{ id, name, priority: 1-10, when: 'expr', interpretation: '2 sentences, what the pattern means', recommendation: '1 concrete action',
  steps: ['optional 3-4 steps → becomes a Try this card'], loop: ['Issue arises','You push for resolution now','Partner withdraws',...], interrupt: ['...'] }
```
`loop`/`interrupt` only for the Conflict & Repair assessment (start the steps you control with "You …").
Write cross-dimension patterns — they are the most valuable part. Cover the combinations a real person would have.

### Plan
`plan.byDim[dimId] = { priority: 'one sentence', weeks: ['Week 1 action. Detail.', 'Week 2…', 'Week 3…', 'Week 4…'] }`
for EVERY dimension (the engine picks the three lowest). Each week string: short imperative title, then a period,
then one sentence of detail. For parenting assessments also `plan.byAge = { '0–5': [3 tips], '6–9': [...], '10–12': [...], '13–15': [...], '16–18': [...], 'Adult child': [...] }`.

### Summaries
Three rules: `overall >= 75`, `overall >= 55`, `true`, each using `{name}`, `{top}`, `{bottom}`.

## Per-assessment notes

- **Conflict & Repair** (`conflict-repair`, couples, icon repair): dims conflictInitiation, escalation, defensiveness,
  withdrawal, pursuit, regulation, accountability, compromise, repair, resolution (score HIGH = healthy; so "withdrawal"
  high means you rarely withdraw, name it "Staying Engaged"; "pursuit" high = "Patience in Pursuit"; "escalation" high =
  "Keeping It Cool" — name dims so high is good). Situational items tag: pursue, withdraw, escalate, defend, repair, avoid.
  Patterns MUST include loops: Pursue→Withdraw, Criticize→Defend, Escalate→Regret, Avoid→Resentment, Discuss→Repair
  (each with `loop` 5–6 steps and `interrupt` 3–4 steps). features: {} .
- **Love, Connection & Appreciation** (`connection-appreciation`, couples, icon heart): dims verbal, affection,
  sharedTime, practicalSupport, emotionalPresence, sharedExperiences, thoughtfulness, reliability, intimacy,
  growth. EVERY item has `facet: 'give'` (how I show it) or `facet: 'receive'` (how I feel loved when…), roughly
  2 give + 2 receive per dim, no reverse-scored items in this one (use frequency and preference wording instead).
  `features: { giveReceive: true }`. Original framework only.
- **Relationship Expectations Alignment** (`expectations-alignment`, couples, icon scale): dims = areas money,
  household, parenting, career, family, social, independence, affection, intimacy, communication, lifestyle, future.
  Score = how clearly discussed and agreed that area is ("We have talked about debt and agree" / "I assume my
  partner wants the same as me about children without having discussed it" reverse). `features: { alignment: true }`.
  Report sections lean on "3 areas you should discuss". 3–4 items per area (12 areas → ~42 items).
- **Emotional Safety & Trust** (`emotional-safety`, couples, icon shield): dims reliability, honesty, availability,
  respect, predictability, vulnerability, boundaries, reassurance, independence, trustRecovery.
  `features: { lists: true }`, `listsTitle: 'Safety and trust, in practice'`, and
  `lists: { safe: { title: 'What helps you feel safe', from: 'high', n: 5, text: { dimId: '...' } }, disconnect: { title: 'What causes you to feel disconnected', from: 'low', n: 5, text: {...} }, needs: { title: 'What your partner may need from you', from: 'low', n: 5, text: {...} } }`
  (text for EVERY dim in each list).
- **Better Partner** (`better-partner`, couples, icon star): dims listening, appreciation, affection, accountability,
  reliability, patience, availability, support, household, conflict, initiative, qualityTime, respect, growth (14 dims,
  3 items each ≈ 42 + 3 situational). Strictly "I…" statements. `features: { becoming: true }` and
  `challenges: { dimId: '7-day challenge sentence' }` for every dim.
- **Fatherhood** (`fatherhood`, parenting, icon child): may say "father"/"dad". dims presence, emotional, encouragement,
  discipline, consistency, teaching, protection, independence, play, modeling, communication, affection, patience,
  reliability (14 dims × 3 items ≈ 42 + 3 situational). `subject` block (see parent-child) is NOT used; instead
  `context` includes `{ id: 'childAge', label: "Your child's age (pick one child to think about)", options: ['0–5','6–9','10–12','13–15','16–18','Adult child'] }`
  and set `ageField: 'childAge'`. Report includes "the father your child may experience" → write `summaries` in that
  voice ("Your responses suggest your child likely experiences you as…") and `others` level texts as "your child may…".
  Never claim to know the child's thoughts: "your responses suggest your child may benefit from…".
- **Motherhood / Parenting** (one file registering TWO slugs via a builder function `function parentingConfig(variant)`
  called for `'motherhood'` (name "Motherhood Strengths & Growth Profile", may say mother/mom) and `'parenting'`
  (name "Parenting Strengths & Growth Profile", universal wording). dims emotionalAvailability, nurturing, boundaries,
  discipline, communication, independence, encouragement, consistency, advocacy, teaching, patience, play, modeling,
  selfCare (balance). Self-care: sustainability, never "you are failing because you are tired".
  `features: { overdoing: true }`: add items with `facet: 'over'` (rescuing, overprotecting, solving every problem,
  excessive monitoring, not allowing consequences — these are `reverse: true` for their dim) and `facet: 'under'`
  (under-involvement, inconsistent boundaries, insufficient structure — also `reverse: true`), ≥5 of each, and
  `overdoing: { over: { dimId: 'what doing too much looks like here' }, under: { dimId: '...' } }` for the dims those
  items point at. Same childAge context + ageField + plan.byAge as Fatherhood.
- **Parent–Child Connection** (`parent-child`, parenting, icon users): the parent chooses ONE child:
  `subject: { title: 'Which child is this about?', blurb: 'Take it once per child — each gets its own report.', fields: [ { id: 'name', label: "Child's first name", placeholder: 'e.g. Emily' }, { id: 'age', label: 'Age', options: ['1','2',...,'17','18','Adult'] } ] }`
  and `ageField: 'age'`. dims communication, trust, emotional, qualityTime, discipline, respect, independence,
  understanding, availability, encouragement, conflict, enjoyment, attention (technology/attention), knowledge
  (knowledge of child's life). Use the spec's example questions. `overallLabel: 'Connection score'`.
  Add `perspective: 'parent'` and `mirror: { itemId: "child-version wording" }` for at least 10 items (e.g.
  "I listen when {child} is upset" → "My parent listens when I'm upset") so a child version can be added later.
  Starters are things to try WITH the child this month (`startersSub: 'Three things to try this month — start with one.'`).

## Quality bar
Before finishing a file: valid JS (`node -e "…"`), every dim has 3 full levels with all 7 fields, every dim has a
plan entry, 35–55 items, patterns reference only real dim ids and tags, no "undefined". Write like the exemplar —
this is a product people would pay for, not a quiz.