{
  "schema_version": "1.0.0",
  "design_system_version": "dd8d236c588e8851461c0f7c727642edb17388d6",
  "generated_at": "2026-04-12T23:25:50.460Z",
  "source_repo": "https://github.com/HAVENGlobal2025/design-from-love",
  "source_branch": "northstar",
  "human_readable_reference": "/FOH_REFERENCE.md",
  "schema_docs": "/docs/foh-reference-schema.md",
  "foh_role": {
    "description": "The Front-of-House Orchestrator (FOH) is the single member-facing agent. The only agent allowed to speak directly with members.",
    "golden_rule": "The Orchestrator always speaks as the Haven guide. It never exposes backend agents, systems, or implementation details.",
    "is": [
      "A guide for resilience planning",
      "A translator of climate, risk, and adaptation complexity",
      "A project manager for action-ready plans"
    ],
    "is_not": [
      "An authority issuing directives",
      "A replacement for professional judgment",
      "An alarm system or fear amplifier"
    ],
    "responsibilities": [
      "Interpret member input (voice, text, UI actions)",
      "Translate complexity into clarity",
      "Create, deliver, and manage Projects",
      "Populate the canvas with UI via ui_patch operations",
      "Coordinate Domain Agents without exposing them to the member",
      "Maintain trust, agency, and emotional attunement",
      "Manage memory, consent, and emotion signals"
    ]
  },
  "surfaces": {
    "dashboard": {
      "description": "Member home view. FOH surfaces project previews, recommendations, and resource center content.",
      "allowed_components": [
        "card",
        "badge",
        "button",
        "progress",
        "skeleton"
      ],
      "layout_constraints": {
        "max_project_preview_cards": 2,
        "cta_button_variants": [
          "default",
          "outline"
        ],
        "progress_bar_height": "h-2",
        "resource_center_position": "sidebar or bottom section — never occludes main content"
      },
      "allowed_ui_patch_ops": [
        "upsert_project_preview_card",
        "remove_project_preview_card",
        "update_resource_center",
        "add_cta",
        "show_notification"
      ]
    },
    "project_create": {
      "description": "Project creation flow, surfaced from dashboard or voice intent.",
      "allowed_components": [
        "card",
        "badge",
        "button",
        "progress",
        "checkbox"
      ],
      "layout_constraints": {
        "first_section": "project_aim",
        "progress_indicator": "visible from step 1",
        "climate_data": "display only — no inline editing"
      },
      "allowed_ui_patch_ops": [
        "set_project_aim",
        "add_action_item",
        "set_project_status",
        "set_project_metadata",
        "add_climate_insight_card",
        "add_local_considerations_card"
      ]
    },
    "project_view": {
      "description": "Full project detail view. Members see all sections, can check off tasks, track budget.",
      "allowed_components": [
        "card",
        "badge",
        "progress",
        "checkbox",
        "button",
        "separator",
        "alert"
      ],
      "layout_constraints": {
        "section_order": [
          "project_aim",
          "project_header",
          "location_analysis",
          "benefits_and_next_steps",
          "action_plan_checklist",
          "budget_tracking",
          "climate_insights",
          "local_considerations",
          "family_preparedness",
          "provider_connections",
          "resources_section"
        ],
        "budget_colors": {
          "spent": "haven-green",
          "committed": "haven-gold",
          "remaining": "bg-muted"
        },
        "provider_cards": {
          "required_badge": "Vetted",
          "cta_variant": "outline"
        }
      },
      "allowed_ui_patch_ops": [
        "update_task_status",
        "update_project_progress",
        "add_climate_insight_card",
        "update_budget",
        "add_action_item",
        "mark_task_complete",
        "add_provider_card",
        "add_resources_section"
      ]
    },
    "onboarding": {
      "description": "First-time member experience. FOH gathers context to personalize.",
      "allowed_components": [
        "card",
        "button",
        "progress"
      ],
      "layout_constraints": {
        "questions_per_turn": 1,
        "progress_bar": "visible at top always",
        "project_creation": "not allowed — context gathering only"
      },
      "allowed_ui_patch_ops": [
        "set_member_context",
        "advance_onboarding_step",
        "complete_onboarding"
      ]
    },
    "voice_overlay_dashboard": {
      "description": "Voice interaction overlay rendered over the dashboard. Minimal UI — conversation first.",
      "allowed_components": [
        "card"
      ],
      "layout_constraints": {
        "position": "centered overlay",
        "max_text_lines": 2,
        "max_text_chars": 120,
        "button_types": [
          "dismiss",
          "confirm"
        ]
      },
      "allowed_ui_patch_ops": [
        "show_voice_message",
        "hide_voice_overlay",
        "trigger_dashboard_action"
      ]
    },
    "voice_overlay_project": {
      "description": "Voice interaction overlay rendered over a project view.",
      "allowed_components": [
        "card"
      ],
      "layout_constraints": {
        "position": "bottom anchor",
        "max_text_lines": 2,
        "max_text_chars": 120,
        "button_types": [
          "dismiss",
          "confirm"
        ]
      },
      "allowed_ui_patch_ops": [
        "show_voice_message",
        "hide_voice_overlay",
        "update_task_from_voice",
        "mark_task_complete"
      ]
    },
    "project_collection": {
      "description": "Browsing view for all member projects. Shows compact summary cards in a responsive grid. Each card links to a dedicated project detail page — no inline task expansion.",
      "allowed_components": [
        "card",
        "badge",
        "progress",
        "button"
      ],
      "layout_constraints": {
        "card_content": "summary only — title (1 line), description (2 lines max), status badge, progress bar, task count, 'View Project' CTA",
        "grid_columns": {
          "mobile": 1,
          "tablet": 2,
          "desktop": "3 project columns + 1 stats sidebar column"
        },
        "no_inline_expansion": true,
        "click_navigates_to": "project_view surface at /project/:id or /adaptation-project/:id",
        "new_project_card": "dashed-border card at end of grid with + icon",
        "stats_sidebar": "Quick Stats card showing active/planned/completed counts and overall progress"
      },
      "allowed_ui_patch_ops": [
        "upsert_project_summary_card",
        "remove_project_summary_card",
        "update_collection_stats",
        "navigate_to_project"
      ]
    }
  },
  "components": {
    "import_base": "@/components/ui",
    "allowed": {
      "card": {
        "sub_components": [
          "card-header",
          "card-title",
          "card-description",
          "card-content"
        ],
        "import": "@/components/ui/card"
      },
      "button": {
        "variants": [
          "default",
          "destructive",
          "outline",
          "secondary",
          "ghost",
          "link"
        ],
        "sizes": [
          "default",
          "sm",
          "lg",
          "icon"
        ],
        "import": "@/components/ui/button"
      },
      "badge": {
        "import": "@/components/ui/badge"
      },
      "progress": {
        "import": "@/components/ui/progress"
      },
      "checkbox": {
        "import": "@/components/ui/checkbox"
      },
      "separator": {
        "import": "@/components/ui/separator"
      },
      "alert": {
        "import": "@/components/ui/alert"
      },
      "skeleton": {
        "import": "@/components/ui/skeleton"
      }
    },
    "task_state_components": {
      "todo": {
        "icon": "Circle",
        "border": "border-dashed border-muted-foreground/30",
        "background": "bg-muted/30",
        "text": "text-haven-navy"
      },
      "in_progress": {
        "icon": "Clock",
        "icon_color": "text-haven-gold",
        "border": "border-haven-gold",
        "background": "bg-haven-gold/5"
      },
      "completed": {
        "icon": "Check",
        "icon_background": "bg-haven-green",
        "icon_color": "text-white",
        "border": "border-haven-green",
        "background": "bg-haven-green/5",
        "strikethrough": false
      }
    },
    "project_status_badges": {
      "in_progress": {
        "bg": "#78BC6B",
        "text": "white"
      },
      "planned": {
        "bg": "#FAB26B",
        "text": "white"
      },
      "suggested": {
        "bg": "#E4E98C",
        "text": "haven-navy"
      },
      "completed": {
        "bg": "#72A08F",
        "text": "white"
      }
    }
  },
  "haven_ui_blocks": {
    "description": "Canonical agentic interaction layer. Every FOH response that produces UI must emit blocks conforming to this envelope. See design-from-love ComponentRegistry for full contract details.",
    "spec_version": "haven_ui_spec.v1-beta",
    "block_types": [
      "next_step_card",
      "explanation_panel",
      "progress_indicator",
      "priority_card",
      "project_panel",
      "step_item",
      "onboarding_step"
    ],
    "block_states": [
      "loading",
      "decision-ready",
      "confirmation",
      "in-progress",
      "completed",
      "error",
      "blocked",
      "requires-input"
    ],
    "action_modes": [
      "read_action",
      "soft_action",
      "write_action"
    ],
    "base_block_fields": {
      "id": "string — unique block identifier",
      "type": "HavenUIBlockType — one of block_types",
      "priority": "number — rendering order within a response (not life priority)",
      "state": "HavenUIBlockState — one of block_states",
      "provenance": "ProvenanceMeta — optional source_label, confidence, reasoning, user_confirmed"
    },
    "composition_rules": {
      "max_primary_blocks": 1,
      "max_supporting_blocks": 2,
      "primary_block_types": [
        "next_step_card",
        "onboarding_step"
      ],
      "supporting_block_types": [
        "explanation_panel",
        "progress_indicator",
        "priority_card",
        "project_panel"
      ],
      "nested_only_in_v1": [
        "step_item"
      ]
    },
    "semantic_id_mapping": {
      "canonical": [
        "priority_id",
        "project_id",
        "step_id"
      ],
      "aliases": {
        "outcome_id": "priority_id",
        "goal_id": "priority_id",
        "guided_step_id": "step_id",
        "action_id": "step_id"
      }
    },
    "safety_rules": [
      "All write_actions must pass through confirmation state",
      "All write_actions must be clearly labeled in UI",
      "No component may perform a silent write",
      "Supporting components must not initiate write_actions directly",
      "StepItemBlock is nested-only in v1 and must not appear top-level"
    ]
  },
  "design_tokens": {
    "semantic": {
      "background": "bg-background",
      "foreground": "text-foreground",
      "primary": "bg-primary / text-primary",
      "muted_foreground": "text-muted-foreground",
      "card": "bg-card",
      "border": "border-border",
      "muted": "bg-muted"
    },
    "brand_palette": {
      "haven-navy": {
        "tailwind": "haven-navy",
        "css_var": "--haven-navy",
        "usage": "Primary brand, headings, text emphasis"
      },
      "haven-electric-yellow": {
        "tailwind": "haven-electric-yellow",
        "css_var": "--haven-electric-yellow",
        "usage": "Primary accent, in-progress states, gold alias"
      },
      "haven-off-white": {
        "tailwind": "haven-off-white",
        "css_var": "--haven-off-white",
        "usage": "Light backgrounds, cream alias"
      },
      "haven-turquoise": {
        "tailwind": "haven-turquoise",
        "css_var": "--haven-turquoise",
        "usage": "Teal alias, section accents"
      },
      "haven-coastal-green": {
        "tailwind": "haven-coastal-green",
        "css_var": "--haven-coastal-green",
        "usage": "Completed states, green alias"
      },
      "haven-sage-green": {
        "tailwind": "haven-sage-green",
        "css_var": "--haven-sage-green",
        "usage": ""
      },
      "haven-fog": {
        "tailwind": "haven-fog",
        "css_var": "--haven-fog",
        "usage": ""
      },
      "haven-periwinkle": {
        "tailwind": "haven-periwinkle",
        "css_var": "--haven-periwinkle",
        "usage": ""
      }
    },
    "projects_surface_aliases": {
      "haven-teal": "haven-turquoise",
      "haven-gold": "haven-electric-yellow",
      "haven-green": "haven-coastal-green",
      "haven-cream": "haven-off-white"
    },
    "typography": {
      "display": {
        "tailwind": "font-display tracking-tighter",
        "font": "Work Sans",
        "usage": "Project titles, section headings"
      },
      "body": {
        "tailwind": "font-sans",
        "font": "Inter",
        "usage": "Body copy, task descriptions"
      },
      "caption": {
        "tailwind": "text-sm text-muted-foreground",
        "usage": "Metadata, dates, cost estimates"
      }
    },
    "gradients": {
      "gradient-primary": "Navy → Turquoise; hero sections, primary CTAs",
      "gradient-accent": "Electric Yellow → Coastal Green; highlights",
      "gradient-subtle": "Vertical light gradient",
      "shadow-glow": "Yellow glow; accent focus"
    }
  },
  "copy_rules": {
    "tone": [
      "Calm, clear, and grounded",
      "Trusted guide — not an authority",
      "Plain language — no jargon, no technical terms",
      "Specific and actionable — not vague or inspirational",
      "Acknowledge uncertainty honestly: 'research suggests', 'projections indicate', 'this may vary'",
      "Lead with what members can do — not what they should fear"
    ],
    "forbidden_words": [
      "crisis",
      "catastrophe",
      "disaster",
      "doomsday",
      "devastating",
      "you're in danger",
      "it's only going to get worse",
      "you need to act now or else",
      "definitely",
      "certainly",
      "guaranteed",
      "will definitely happen",
      "the AI",
      "the algorithm",
      "the model",
      "the agent",
      "the backend",
      "the system",
      "Domain Agent",
      "Sub-Agent",
      "Migration Agent",
      "Adaptation Agent",
      "Risk Agent",
      "you must",
      "you have to",
      "you have no choice"
    ],
    "phrasing_rules": [
      {
        "context": "projections",
        "preferred": [
          "Research suggests",
          "Projections indicate",
          "Data shows"
        ],
        "avoid": [
          "Will",
          "Definitely",
          "For certain"
        ]
      },
      {
        "context": "recommendations",
        "preferred": [
          "One option to consider",
          "You might want to",
          "Many members find it helpful to"
        ],
        "avoid": [
          "You should",
          "You must",
          "I recommend you"
        ]
      },
      {
        "context": "project_creation",
        "preferred": [
          "I've put together a plan for you",
          "Here's a starting point"
        ],
        "avoid": [
          "I've done this for you",
          "This is what you need to do"
        ]
      },
      {
        "context": "uncertainty",
        "preferred": [
          "I don't have enough information on that yet",
          "I'd want to look into that more"
        ],
        "avoid": [
          "Guessing or fabricating data"
        ]
      },
      {
        "context": "progress",
        "preferred": [
          "You've made real progress",
          "That's done"
        ],
        "avoid": [
          "Good job",
          "You did great"
        ]
      },
      {
        "context": "climate_risk",
        "preferred": [
          "Your area may experience more [X] over time"
        ],
        "avoid": [
          "Your home will flood",
          "You're at high risk"
        ]
      }
    ],
    "project_aim_formula": "[Action verb] [household/business vulnerability or goal] by [specific intervention], resulting in [measurable outcome].",
    "project_aim_action_verbs": [
      "Reduce",
      "Improve",
      "Prepare",
      "Relocate",
      "Strengthen",
      "Build"
    ]
  },
  "interaction_rules": {
    "progressive_disclosure": "Surface one idea or step at a time. Never overwhelm with multiple asks in a single turn.",
    "project_first": "Every meaningful goal becomes a Project. Insights without action are never the end state.",
    "create_offer_flow": {
      "description": "When member intent indicates a viable project, FOH creates it immediately, surfaces a preview card on dashboard, and follows member's lead from there.",
      "steps": [
        "Detect viable project intent from member conversation",
        "Create project immediately — no confirmation gate",
        "Emit upsert_project_preview_card to dashboard surface",
        "CTA on card navigates to project page",
        "On project page, FOH becomes project-bound"
      ],
      "follow_member_lead": "If member navigates away, FOH follows. Never force member back to project."
    },
    "voice_gui_coherence": "Every ui_patch triggered by a voice turn must align with what FOH says in that turn. Never update UI silently.",
    "levels_of_agency": [
      {
        "level": "Inform",
        "description": "Surface signals, risks, and context",
        "consent_required": false
      },
      {
        "level": "Recommend",
        "description": "Propose Projects and actions",
        "consent_required": false
      },
      {
        "level": "Assist",
        "description": "Break actions into guided steps",
        "consent_required": "implicit"
      },
      {
        "level": "Support Execution",
        "description": "Track progress, monitor outcomes",
        "consent_required": "explicit"
      }
    ],
    "higher_agency_requirements": [
      "Clear framing",
      "Member consent",
      "Reversibility and control"
    ]
  },
  "ui_patch_ops": {
    "upsert_project_preview_card": {
      "allowed_surfaces": [
        "dashboard"
      ],
      "payload": {
        "project_id": "string (required)",
        "title": "string (required)",
        "description": "string",
        "status": "Suggested | Planned | In Progress | Completed",
        "progress_pct": "number 0–100",
        "cta_label": "string",
        "cta_route": "string (e.g. /projects/{project_id})"
      }
    },
    "remove_project_preview_card": {
      "allowed_surfaces": [
        "dashboard"
      ],
      "payload": {
        "project_id": "string (required)"
      }
    },
    "update_resource_center": {
      "allowed_surfaces": [
        "dashboard"
      ],
      "payload": {
        "files": "array of { name, type, url }",
        "reports": "array of { name, date, type, url }"
      }
    },
    "add_cta": {
      "allowed_surfaces": [
        "dashboard"
      ],
      "payload": {
        "label": "string (required)",
        "route": "string (required)",
        "variant": "default | outline"
      }
    },
    "show_notification": {
      "allowed_surfaces": [
        "dashboard"
      ],
      "payload": {
        "message": "string (required, max 160 chars)",
        "type": "info | success | warning"
      }
    },
    "set_project_aim": {
      "allowed_surfaces": [
        "project_create"
      ],
      "payload": {
        "aim_text": "string (required, follows aim formula)"
      }
    },
    "add_action_item": {
      "allowed_surfaces": [
        "project_create",
        "project_view"
      ],
      "payload": {
        "task_id": "string (required)",
        "title": "string (required)",
        "description": "string",
        "state": "todo | in_progress | completed",
        "due_date": "ISO date string",
        "estimated_cost": "string (e.g. '$250–$400')"
      }
    },
    "set_project_status": {
      "allowed_surfaces": [
        "project_create",
        "project_view"
      ],
      "payload": {
        "project_id": "string (required)",
        "status": "Suggested | Planned | In Progress | Completed"
      }
    },
    "set_project_metadata": {
      "allowed_surfaces": [
        "project_create"
      ],
      "payload": {
        "title": "string (required)",
        "description": "string",
        "type": "adaptation | migration | safety"
      }
    },
    "add_climate_insight_card": {
      "allowed_surfaces": [
        "project_create",
        "project_view"
      ],
      "payload": {
        "headline": "string",
        "trends": "array of { icon, title, description }",
        "projections": "array of { stat, label }",
        "data_source": "string (e.g. 'NOAA climate projections')"
      }
    },
    "add_local_considerations_card": {
      "allowed_surfaces": [
        "project_create",
        "project_view"
      ],
      "payload": {
        "building_codes": "string",
        "local_incentives": "string",
        "seasonal_timing": "string",
        "advisory": "string (optional)"
      }
    },
    "update_task_status": {
      "allowed_surfaces": [
        "project_view"
      ],
      "payload": {
        "task_id": "string (required)",
        "state": "todo | in_progress | completed"
      }
    },
    "mark_task_complete": {
      "allowed_surfaces": [
        "project_view",
        "voice_overlay_project"
      ],
      "payload": {
        "task_id": "string (required)",
        "completed_date": "ISO date string"
      }
    },
    "update_project_progress": {
      "allowed_surfaces": [
        "project_view"
      ],
      "payload": {
        "project_id": "string (required)",
        "progress_pct": "number 0–100"
      }
    },
    "update_budget": {
      "allowed_surfaces": [
        "project_view"
      ],
      "payload": {
        "total": "number",
        "spent": "number",
        "committed": "number",
        "remaining": "number",
        "line_items": "array of { title, date, amount, state: paid|committed|estimated }"
      }
    },
    "add_provider_card": {
      "allowed_surfaces": [
        "project_view"
      ],
      "payload": {
        "provider_type": "string (e.g. 'HVAC Contractors')",
        "description": "string",
        "cta_label": "string",
        "vetted": true
      }
    },
    "add_resources_section": {
      "allowed_surfaces": [
        "project_view"
      ],
      "payload": {
        "categories": "array of { title, items: string[] }"
      }
    },
    "set_member_context": {
      "allowed_surfaces": [
        "onboarding"
      ],
      "payload": {
        "key": "location | household_composition | housing_type | environmental_concerns | goals | communication_preferences",
        "value": "string | object"
      }
    },
    "advance_onboarding_step": {
      "allowed_surfaces": [
        "onboarding"
      ],
      "payload": {
        "step_number": "number (required)",
        "total_steps": "number (required)"
      }
    },
    "complete_onboarding": {
      "allowed_surfaces": [
        "onboarding"
      ],
      "payload": {}
    },
    "show_voice_message": {
      "allowed_surfaces": [
        "voice_overlay_dashboard",
        "voice_overlay_project"
      ],
      "payload": {
        "text": "string (required, max 120 chars)"
      }
    },
    "hide_voice_overlay": {
      "allowed_surfaces": [
        "voice_overlay_dashboard",
        "voice_overlay_project"
      ],
      "payload": {}
    },
    "trigger_dashboard_action": {
      "allowed_surfaces": [
        "voice_overlay_dashboard"
      ],
      "payload": {
        "action": "create_project | open_resource_center | navigate_to_project | show_notification"
      }
    },
    "update_task_from_voice": {
      "allowed_surfaces": [
        "voice_overlay_project"
      ],
      "payload": {
        "task_id": "string (required)",
        "new_state": "todo | in_progress | completed"
      }
    },
    "upsert_project_summary_card": {
      "allowed_surfaces": [
        "project_collection"
      ],
      "payload": {
        "project_id": "string (required)",
        "title": "string (required, 1 line max)",
        "description": "string (2 lines max)",
        "status": "Not Started | Planned | In Progress | Completed",
        "progress_pct": "number 0–100",
        "task_count": "string (e.g. '3 of 7 tasks')",
        "detail_route": "string (e.g. /project/:id or /adaptation-project/:id)"
      }
    },
    "remove_project_summary_card": {
      "allowed_surfaces": [
        "project_collection"
      ],
      "payload": {
        "project_id": "string (required)"
      }
    },
    "update_collection_stats": {
      "allowed_surfaces": [
        "project_collection"
      ],
      "payload": {
        "active": "number",
        "planned": "number",
        "completed": "number",
        "overall_progress_pct": "number 0–100"
      }
    },
    "navigate_to_project": {
      "allowed_surfaces": [
        "project_collection"
      ],
      "payload": {
        "project_id": "string (required)",
        "route": "string (required, e.g. /project/:id or /adaptation-project/:id)"
      }
    }
  },
  "glossary": {
    "haven": "A California-based startup committed to enabling resilience and thriving for everyone.",
    "member_types": [
      "Households (HH)",
      "Businesses (SMB)",
      "Communities (COM)"
    ],
    "foh": "Front-of-House Orchestrator. The single member-facing agent. Only agent allowed to speak directly with members. Represented as the Haven logo orb in product.",
    "domain_agents": [
      "Migration Agent",
      "Adaptation Agent",
      "Risk Agent"
    ],
    "report": "Structured document generated by Domain Agents. Delivered as JSON + PDF to FOH. Stored in Resource Center.",
    "report_naming_convention": "{Type} Report - {Month}_{Day}_{Year}",
    "project": "Structured, guided action plan delivered exclusively by FOH. Composed of action items and design kit elements.",
    "resource_center": "Location for all files shared between members and FOH. Located on Home Dashboard. Supports PDF, JPEG, .doc.",
    "canvas": "Graphical co-creation space for building and executing Projects with FOH.",
    "dashboard": "Member home view. Contains project previews, Resource Center, and FOH chat entry."
  }
}