RIFF design doc · v3 · 2026-07-06 · reviewed with Codex (15 findings addressed) · markdown twin: docs/config-cascade-and-branding.md

The Config Cascade & Per-Business Branding

Every flow gets its own branded follow-along link, and every configuration question gets a one-lookup answer.

1 · The problem, in three sentences

• Branding: web/companion.html guesses a theme by substring-matching the flow id ("plumb" → blue). New flows silently render as the space channel.
• Sprawl: a flow's behavior is assembled from pack YAML, flow YAML, env vars, the record-policy cascade, the LLM-policy inheritance, and the voice hierarchy — six mechanisms, no single answer to "what is this flow's config and why."
• Sharing: flow families already exist (space_channel ×3; capsule_law's two legal flows share one 10DLC SMS campaign) but each flow re-declares shared facts, and they drift.

2 · The cascade — six levels, plain nouns

Most specific wins. Only one level is new.

3 · Five domains, one file per org

# orgs/capsule_law.org.yaml
org_id: capsule_law
display_name: "Capsule Law"
brand:   {badge: "CL", tagline: "your intake, live",
          colors: {primary: "#c8a24a", highlight: "#e2c56f", bg: "#0b0e19", panel: "#131730"},
          theme: null}            # optional ALLOWLISTED theme name — never a css path
telecom: {sms_campaign: C51GVEC}  # identity only; numbers/routing stay in env
policy:  {record: on, companion_privacy: phone_verified}
llm:     {default: gemini-2.5-flash}
voice:   {voice_id: en_GB-alba-medium, style: warm}

• Flows point at their org (org: capsule_law) — one direction only; the org file has no member list, so membership can't drift. A dangling reference is a lint error.
• The five domains (brand / telecom / policy / llm / voice) resolve independently — sharing SMS identity while overriding voice is normal. A flow overrides a domain; it never joins a second org.
• Safety is monotonic: policy.* may only tighten downstream. An org's record: off can never be flipped on by a state. Loosening is a load error.

4 · One resolver, with provenance

riff/effective_config.py · resolve(flow_id, state_id=None) + apply_call_overlay(cfg, overlay) for per-call overrides — runs at load time; every value carries its source. The existing record-policy and LLM-policy cascades migrate onto this resolver (behavior-preserving, full-suite diff as the bar) so there is exactly one implementation — and the answer below is always true, never a guess:

Env vars stay the deployment layer forever — phone routing, numbers, and keys never migrate into git.

5 · Branding rides the cascade PR3 SHIPPED

Hands-on guide: How-To — Brand Your Flow's Follow-Along Page (colors, badge, tagline, and journey: caller-friendly step labels). Note: the flow's MENU and live PROGRESS were always per-flow (they're data); branding adds the look and the journey wording.

• The resolved brand is served at request time by brand_for_flow() — kept out of the prompt-facing business_profile. (A compiled ui_brand field is the PR4 end-state.)
• The public bearer link gets colors, name, badge, tagline — no provenance, no internal ids.
• Bespoke looks (space channel's starfield) become allowlisted named themes shipped in-repo — never arbitrary CSS paths, so contrast checks and screenshots stay trustworthy.
• Keyword mapping stays as the mid-priority fallback until PR4, then dies. Missing brand on a production flow is a lint warn today, hardening to error at PR4; hash-derived palettes cover otherwise-unbranded flows.
• One ui_brand object feeds the companion page, the intake live mirror, and the Line Page — link, mirror, and operator view always match.

6 · The admin portal — grows in three deliberate steps

7 · Rollout

8 · Decided & rejected (Codex review)

9 · Backlog