Skip to main content

​
Overview

Onboarding a new family involves creating their directory structure, configuring phone routing, setting up member profiles, and establishing initial communication. Each family is a self-contained workspace under fork/workspace/families/.
The family_id becomes the directory name (e.g., kano) and is used throughout the system to identify this care network.

​
Directory Structure

Each family follows a consistent structure: 
fork/workspace/families/
└── {family_id}/
    ├── routing.json          # Phone → member mapping (runtime reads this)
    ├── family.md             # Family operational state (schedule, meds, events)
    └── members/
        └── {name}.md         # Individual member profile

​
Key Files

​
routing.json
file
required
Maps phone numbers to family members. The runtime uses this to identify who’s texting and what access level they have.
​
family.md
file
required
Central care coordination document containing care recipient info, care team roster, schedule, medications, and operational notes. Split into Current (always loaded) and Reference (loaded on demand) sections.
​
members/{name}.md
file
required
Individual member profiles that personalize agent interactions. Starts sparse and grows through conversation.

​
Onboarding Steps

1

Create Family Directory

Create the directory structure for the new family:
mkdir -p fork/workspace/families/{family_id}/members
Choose a meaningful family_id (typically last name in lowercase, e.g., kano).
2

Create routing.json

Set up phone number mapping with at least one member (typically the primary caregiver):
{
  "family_id": "kano",
  "members": {
    "+16517037981": {
      "name": "Liban",
      "role": "primary_caregiver",
      "access_level": "full",
      "active": true
    }
  },
  "care_recipient": "Degitu",
  "status": "active",
  "created": "2026-02-25",
  "notes": "Cold start. All care details to be learned through conversation."
}
The chat_id field is populated automatically after the first message exchange. Leave it empty during initial setup.
3

Create family.md from Template

Use the template at fork/workspace/families/template/family.md to create the family’s operational document:
cp fork/workspace/families/template/family.md \
   fork/workspace/families/{family_id}/family.md
Update the frontmatter with family-specific details:
---
family_id: "kano"
created: "2026-02-25"
last_updated: "2026-02-25T00:00:00Z"
primary_caregiver: "+16517037981"
care_recipient: "Degitu"
status: active
---
4

Create Member Profiles

Create a profile for each member in routing.json:
# Liban Kano — Member Profile

## Identity
- Name: Liban Kano
- Phone: +16517037981
- Role: Primary caregiver, family coordinator
- Relationship to care recipient: Grandson
- Access level: full

## Communication Preferences
<!-- Learned through interaction — not pre-loaded -->
- Preferred channel: iMessage
- Language:
- Response time expectations:
- Preferred notification hours:

## Care Responsibilities
<!-- What this person handles day-to-day — learned through conversation -->

## Personal Context
<!-- Context that helps CareSupport be human, not clinical -->

## Interaction History
- 2026-02-25: Profile created. Cold start — all details to be learned.
Profiles are intentionally sparse at creation. The runtime agent fills them in via the member_updates field in its JSON response schema.
5

Establish Initial Chat

Send an initial message via Linq CLI to establish the chat_id:
python runtime/scripts/linq_gateway.py create \
  --to "+16517037981" \
  --body "Welcome to CareSupport! I'm here to help coordinate care for your family." \
  --service iMessage
The command will return a chat_id (UUID format).
6

Update routing.json with chat_id

Add the returned chat_id to the member’s entry in routing.json:
{
  "+16517037981": {
    "name": "Liban",
    "role": "primary_caregiver",
    "access_level": "full",
    "active": true,
    "chat_id": "1965f2b5-c5e6-4a08-80e9-9224b8a20d88"
  }
}

​
Phone Resolution Flow

When a message arrives, the system resolves the sender: 
1. poll_inbound.py receives message with from_phone and chat_id
2. Calls handle_sms(from_phone, body, service=service)
3. handle_sms → resolve_member(chat_id, phone)
   a. First tries resolve_chat_id() — scans routing files for matching chat_id
   b. Falls back to resolve_phone() — scans routing files for matching phone
4. If resolved → loads family.md, member profile, builds system prompt
5. If NOT resolved → logs "Unknown phone" and skips
The chat_id resolution is preferred because phone numbers can change or be shared. Always establish chat_id for reliable member identification.

​
Cold Start Philosophy

CareSupport uses a “cold start” approach for new families:
  • Minimal data entry during onboarding
  • Care details learned naturally through conversation
  • Agent updates profiles and family.md via member_updates field
  • Reduces upfront friction and captures real-world context
Do NOT pre-populate extensive details in member profiles or family.md. Let the agent learn through interaction to ensure accuracy and reduce coordinator burden.

​
Verification Checklist

After onboarding, verify:
  • Directory structure exists: families/{family_id}/members/
  • routing.json has at least one member with valid phone
  • family.md has correct frontmatter (family_id, primary_caregiver)
  • Member profile(s) created in members/ directory
  • Initial message sent and chat_id obtained
  • chat_id added to member’s routing.json entry
  • Member can send/receive messages successfully

​
Next Steps

Add Family Members

Learn how to add additional family members, caregivers, and supporters to the care team.

Configure Phone Routing

Deep dive into routing.json schema and phone number mapping.

Set Access Controls

Configure role-based access levels to protect sensitive information.

Build docs developers (and LLMs) love

Get started for freeTalk to us