Service: Shadow Kid Linking User Guide - ad-ha/kidschores-ha GitHub Wiki

Shadow Kid Linking Service - User Guide

Overview

The Shadow Kid Linking service (kidschores.manage_shadow_link) allows you to convert existing kid profiles into shadow kids (or vice versa) without losing any data. This is useful when you already have a parent and a kid with the same name in your system and want to connect them properly.

What Are Shadow Kids?

Shadow kids are special kid profiles that are automatically created when you enable the "Allow chore assignment" option for a parent. They serve as a target for assigning chores to parents while maintaining separate point tracking. Shadow kids:

Share the same name as their parent
Have their own point balance and history
Can be assigned chores like regular kids
Link back to their parent profile
Have notifications disabled by default (to avoid duplicates)

When to Use This Service

Use the linking service when:

✅ You already have a parent profile named "Sarah" and a kid profile named "Sarah" that you want to connect
✅ You want to preserve all the kid's existing points, chores, badges, and history
✅ You need to programmatically manage shadow kid relationships (automations, scripts)
✅ You want to "unlink" a shadow kid back to a regular kid profile

Use the options flow instead when:

⚠️ You're setting up a parent for the first time (just check "Allow chore assignment")
⚠️ The kid profile doesn't exist yet (options flow will create it automatically)

Prerequisites

Before using the shadow kid linking service, ensure:

Both profiles exist: You must have both a parent profile and a kid profile already created
Names match exactly: The parent and kid must have identical names (case doesn't matter)
No existing links: Neither the parent nor the kid should already be linked to another entity
Parent has chore assignment enabled: The parent should have allow_chore_assignment: true set

Service Operations

The service supports two actions: link and unlink.

Link Operation

Converts an existing regular kid profile into a shadow kid linked to a parent.

Parameters

service: kidschores.manage_shadow_link
data:
  name: "Sarah" # Must match BOTH parent and kid name
  action: "link" # Creates the shadow relationship

What Happens During Linking

Validation: The system checks that:
- A parent named "Sarah" exists
- A kid named "Sarah" exists
- The kid is NOT already a shadow kid
- The parent does NOT already have a different shadow kid linked
- The parent has allow_chore_assignment enabled
Kid Profile Update:
- Sets is_shadow_kid: true marker
- Adds linked_parent_id pointing to the parent
- Preserves ALL existing data:
  - Current point balance
  - Point history
  - All assigned chores
  - Badge progress and earned badges
  - Achievement progress
  - Challenge participation
  - Reward claim history
Parent Profile Update:
- Sets linked_shadow_kid_id pointing to the kid
- Enables workflow and gamification by default (enable_chore_workflow: true and enable_gamification: true)
- You can disable these features later via "Manage Parents" → Edit parent if desired
Result: The kid now functions as a shadow kid for the parent with full features enabled by default. Any chores assigned to the kid will notify the parent (if parent notifications are enabled).

Data Preservation Guarantee

EVERYTHING is preserved during linking:

✅ Points (current balance and full history)
✅ All chore assignments (pending, approved, completed)
✅ Badge progress and earned badges
✅ Achievement progress and completed achievements
✅ Challenge participation and progress
✅ Reward claim history
✅ Penalty history
✅ Bonus history
✅ All timestamps and metadata

The linking operation only adds relationship markers (is_shadow_kid, linked_parent_id, linked_shadow_kid_id) without modifying any existing data.

What About Workflow and Gamification Features?

After linking, both features are enabled by default:

✅ Workflow buttons enabled: Kid can claim chores, parent can disapprove
✅ Gamification enabled: Points sensor, badges, rewards, bonuses, penalties all visible

You can disable these features individually:

Go to: KidsChores Integration → Configure → Manage Parents → Edit the parent
Uncheck "Enable chore workflow" to hide claim/disapprove buttons (approval-only mode)
Uncheck "Enable gamification features" to hide points, badges, rewards, bonuses, penalties

Important: Disabling features only HIDES the UI entities - all underlying data remains intact:

🔒 Points balance and history preserved in storage
🔒 Badge progress and earned badges remain untouched
🔒 All reward/bonus/penalty history intact in storage
🔒 Chore completion history preserved regardless of workflow setting
✨ Re-enabling features immediately shows all data again
✨ Unlinking the kid also restores all entities with full data

Think of it as a "show/hide" toggle: The underlying game data (points, badges, history) never goes away - only the UI visibility changes. This allows parents to customize what features their shadow kid can see and interact with, while preserving all progress for when features are re-enabled or the kid is unlinked.

Unlink Operation

Converts a shadow kid back into a regular kid profile, breaking the parent relationship.

Parameters

service: kidschores.manage_shadow_link
data:
  name: "Sarah" # The shadow kid's current name
  action: "unlink" # Breaks the shadow relationship

What Happens During Unlinking

Validation: The system checks that:
- A kid named "Sarah" exists
- The kid IS a shadow kid (has is_shadow_kid: true)
Kid Profile Update:
- Removes is_shadow_kid marker
- Removes linked_parent_id reference
- Automatically renames kid to Sarah_unlinked (prevents name conflicts)
- Restores full workflow and gamification features (regular kids always have all features)
- Preserves ALL existing data (same guarantee as linking)
Parent Profile Update:
- Removes linked_shadow_kid_id reference
- Parent's allow_chore_assignment remains enabled (but with no linked kid)
Device Registry Update:
- Immediately updates the device name in Home Assistant's device registry
- All entity names update instantly (no integration reload required)
Result: The kid is now a regular, independent kid profile named "Sarah_unlinked" with all data intact.

The "_unlinked" Suffix

The unlink operation automatically appends _unlinked to the kid's name to prevent conflicts:

Before unlink: Parent "Sarah", shadow kid "Sarah"
After unlink: Parent "Sarah", regular kid "Sarah_unlinked"

This ensures:

No duplicate names in your system
Clear indication that the kid was previously linked
You can easily rename the kid afterward via the "Manage Kids" options flow

Step-by-Step Examples

Example 1: Link Existing Profiles

Scenario: You have a parent "Mom" and a kid "Mom" with 500 points and 3 active chores. You want to link them.

Steps:

Verify the parent has chore assignment enabled:
- Go to: KidsChores Integration → Configure → Manage Parents → Edit "Mom"
- Ensure "Allow this parent to be assigned chores" is checked
- Save if you made changes
Open Developer Tools → Services
Select the service: kidschores.manage_shadow_link
Fill in the service data:
```
name: "Mom"
action: "link"
```
Click "Call Service"
Verify the result:
- The kid "Mom" entity still exists with the same ID
- All 500 points and 3 chores are preserved
- The kid now shows as a shadow kid in the options flow
- Check sensor.mom_kidschores_ui_dashboard_helper attributes for is_shadow_kid: true

Result: The kid "Mom" is now a shadow kid linked to parent "Mom". All data is preserved.

Example 2: Unlink Shadow Kid

Scenario: You have a shadow kid "Dad" linked to parent "Dad". You want to separate them.

Steps:

Open Developer Tools → Services
Select the service: kidschores.manage_shadow_link
Fill in the service data:
```
name: "Dad"
action: "unlink"
```
Click "Call Service"
Verify the result:
- The kid is renamed to "Dad_unlinked" (check entity names in Home Assistant)
- The kid is now a regular kid (no longer shows shadow marker)
- Parent "Dad" still has allow_chore_assignment enabled but no linked kid
- All points, chores, badges preserved under the new name
(Optional) Rename the kid:
- Go to: KidsChores Integration → Configure → Manage Kids → Edit "Dad_unlinked"
- Change the name to whatever you want (e.g., "Dad - Personal")
- Save

Result: The kid is now independent with a new name, all data intact.

Example 3: Migrating from Workaround Setup

Scenario: You manually created a kid with the same name as a parent as a workaround before this feature existed. Now you want to properly link them.

Your current setup:

Parent: "Sarah" (email: [email protected])
Kid: "Sarah" (650 points, 15 completed chores, 3 badges)

Migration steps:

Enable chore assignment for the parent (if not already enabled):
- KidsChores Integration → Configure → Manage Parents → Edit "Sarah"
- Check "Allow this parent to be assigned chores"
- Save

Link the profiles:

service: kidschores.manage_shadow_link
data:
  name: "Sarah"
  action: "link"

Verify everything works:
- Check dashboard: Kid "Sarah" still shows 650 points
- Verify chores: All 15 completed chores appear in history
- Check badges: All 3 badges are still earned
- Test assigning a new chore to "Sarah" - parent should get supervised notifications

Result: Your workaround setup is now a proper shadow kid relationship without any data loss.

Notification Behavior

Default Settings

When a shadow kid is created (either through linking or through options flow), notifications are disabled by default to prevent duplicates:

Shadow kid: enable_notifications: false
Parent receives notifications for supervised chores

This prevents the parent from receiving the same notification twice (once as the shadow kid, once as the supervising parent).

Enabling Notifications for Shadow Kids

You can enable notifications for shadow kids if needed:

Use cases for enabling:

✅ You want 30-minute due date reminders sent to the kid's device
✅ You're using a different notification service for the kid vs the parent
✅ You want the kid to receive their own notifications in addition to parent supervision

How to enable:

Go to: KidsChores Integration → Configure → Manage Kids → Edit the shadow kid
Scroll to "Mobile notification service"
You'll see a warning:

⚠️ Shadow kid notifications: Parent 'Mom' already receives notifications for supervised chores. Enabling here will create duplicate notifications. Useful for 30-minute due date reminders or if using different notification services.
Select a notification service if you want to proceed
Optionally enable "Due date reminders" for 30-minute alerts
Save

Important: Enabling notifications for shadow kids will result in duplicate notifications for supervised chores (one to the kid, one to the parent). Only enable if you have a specific use case.

Error Messages and Troubleshooting

Common Error Messages

"No kid found with name 'Sarah'"

Cause: The kid profile doesn't exist or the name doesn't match exactly.

Solution:

Check the kid exists: KidsChores Integration → Configure → Manage Kids
Verify the name matches exactly (case-insensitive but must be exact)
If names differ slightly, rename the kid first, then retry the service

"No parent found with name 'Sarah'"

Cause: The parent profile doesn't exist or the name doesn't match exactly.

Solution:

Check the parent exists: KidsChores Integration → Configure → Manage Parents
Verify the name matches exactly
If names differ, rename the parent first, then retry

"Kid 'Sarah' is already linked to a parent"

Cause: The kid is already a shadow kid linked to a parent.

Solutions:

If you want to keep the existing link: No action needed
If you want to relink to a different parent:
1. First unlink the kid: action: "unlink"
2. Rename the kid (remove "_unlinked" suffix if desired)
3. Link to the new parent: action: "link"

"Parent 'Sarah' already has a different shadow kid linked"

Cause: The parent is already linked to a different kid profile.

Solutions:

If you want to keep the existing shadow kid: No action needed
If you want to switch to a different shadow kid:
1. First unlink the existing shadow kid
2. Link the new kid to the parent

Note: Each parent can only have ONE shadow kid at a time.

"Kid 'Sarah' is not linked to any parent"

Cause: You tried to unlink a regular kid that isn't a shadow kid.

Solution:

Verify the kid is actually a shadow kid
Check sensor.sarah_kidschores_ui_dashboard_helper attributes for is_shadow_kid: true
If the kid is already a regular kid, no unlinking is needed

"Parent 'Sarah' does not have chore assignment enabled"

Cause: The parent's allow_chore_assignment setting is disabled.

Solution:

Go to: KidsChores Integration → Configure → Manage Parents → Edit "Sarah"
Check "Allow this parent to be assigned chores"
Save
Retry the linking service

General Troubleshooting Tips

Service doesn't appear in Developer Tools:

Ensure the KidsChores integration is loaded
Check Home Assistant logs for integration errors
Reload the integration if needed

Entity names don't update after unlinking:

This should happen automatically (device registry update)
If names are stale, try reloading the integration
Check Home Assistant logs for device registry errors

Data appears to be missing after linking:

Check the kid's entity states (points sensor, chore sensors)
Verify you're looking at the correct entity ID
Data is never deleted during linking - only relationship markers are added

Need to rename the "_unlinked" kid:

Use the options flow: Manage Kids → Edit the kid → Change name
Or use the kidschores.rename_entity service if available

Advanced Usage

Automations and Scripts

You can use the shadow kid linking service in automations and scripts for advanced workflows.

Example: Auto-link on parent creation

automation:
  - alias: "Auto-link shadow kid on parent setup"
    trigger:
      - platform: event
        event_type: kidschores_parent_added
    condition:
      - condition: template
        value_template: "{{ trigger.event.data.allow_chore_assignment }}"
    action:
      - service: kidschores.manage_shadow_link
        data:
          name: "{{ trigger.event.data.name }}"
          action: "link"

Example: Scheduled unlinking

automation:
  - alias: "Unlink shadow kids at end of month"
    trigger:
      - platform: time
        at: "23:59:59"
    condition:
      - condition: template
        value_template: "{{ now().day == (now() + timedelta(days=1)).replace(day=1).day - 1 }}"
    action:
      - service: kidschores.manage_shadow_link
        data:
          name: "Mom"
          action: "unlink"

Integration with Other Services

The shadow kid linking service works seamlessly with other KidsChores services:

After linking, you can:

Assign chores to the shadow kid: kidschores.assign_chore
Adjust points: kidschores.adjust_points
Grant badges: kidschores.grant_badge
All standard kid operations work identically

Parent supervision:

Parents automatically receive notifications for shadow kid chore updates
Parents can approve/reject chores via their dashboard
Parents see supervised chores in their "Chore Approvals" card

FAQ

Q: Will linking delete my kid's data?

A: No. Linking preserves 100% of the kid's data. The operation only adds relationship markers (is_shadow_kid, linked_parent_id) to the kid profile. All points, chores, badges, history, and other data remain intact.

Q: What happens to points when I link a kid?

A: Nothing changes. The kid's current point balance and entire point history are preserved. The kid continues to accumulate points independently. Linking only establishes the parent-kid relationship for chore supervision purposes. By default, all gamification features (points, badges, rewards) are enabled and visible.

Q: What happens if I disable workflow or gamification features?

A: Disabling these features only hides the UI entities - all underlying data remains safely stored:

When you disable gamification:

❌ Points sensor, badge sensor become invisible
❌ Reward/bonus/penalty buttons disappear
❌ Points adjustment buttons hidden
✅ Points balance and full history preserved in storage
✅ All badge progress and earned badges remain intact
✅ All reward claims and purchase history preserved

When you disable workflow:

❌ Claim and disapprove buttons become invisible
✅ Approve button remains (approval-only mode)
✅ All chore assignments and completion history intact
✅ All approval history preserved

Re-enabling features:

✨ All entities reappear instantly with complete data
✨ No data recovery needed - everything was preserved
✨ Points balances, badge progress, chore history all exactly as before

Unlinking the kid:

✨ Regular kid gets ALL entities back with full data
✨ No feature restrictions - full workflow and gamification restored

Think of it as a "show/hide" toggle: The game data never goes away, only the UI visibility changes. This allows flexible parental control over which features are visible while preserving all progress.

Q: Can I have multiple shadow kids for one parent?

A: No. Each parent can only have ONE shadow kid at a time. This is by design to keep the supervision workflow simple. If you need to change which kid is linked, unlink the current shadow kid first, then link a different kid.

Q: Can a shadow kid be linked to multiple parents?

A: No. Each shadow kid can only be linked to ONE parent. Shadow kids have a single linked_parent_id field. If you need multiple parents to supervise the same chores, consider using the parent collaboration features instead.

Q: Why does the kid get renamed to "_unlinked" when I unlink?

A: The automatic rename prevents name conflicts. After unlinking, the parent "Sarah" and kid "Sarah" would have duplicate names, which causes issues in Home Assistant. The _unlinked suffix:

Prevents the conflict automatically
Clearly indicates the kid was previously linked
Can be changed afterward via the "Manage Kids" options flow

Q: Do I need to reload the integration after linking/unlinking?

A: No. The service updates the coordinator data and refreshes all entities automatically. Changes take effect immediately without requiring an integration reload.

Q: What if I manually delete a shadow kid?

A: If you delete a shadow kid through the "Manage Kids" options flow:

The kid entity is completely removed
The parent's linked_shadow_kid_id is cleared
The parent's allow_chore_assignment is set to false

This is different from unlinking, which preserves the kid as a regular profile.

Q: Can I link a kid that already has chores assigned?

A: Yes! This is one of the main use cases for the linking service. All assigned chores remain intact. The kid continues to work on the same chores, but now the parent receives supervision notifications.

Q: What happens to notifications when I link a kid?

A: When you link a kid, notifications are set to disabled by default (enable_notifications: false) to prevent duplicates. The parent receives notifications for supervised chores instead. You can enable kid notifications afterward via "Manage Kids" if needed (e.g., for 30-minute reminders).

Q: Can I use the service with kids/parents that have special characters in their names?

A: Yes. Names with spaces, accents, apostrophes, and other special characters work fine. The service uses exact name matching (case-insensitive). Examples that work:

"O'Brien"
"José María"
"Sarah-Jane"
"Mom (Work Account)"

Q: What if the linking service fails partway through?

A: The service uses atomic operations. If any validation fails, no changes are made to either the parent or kid profile. The coordinator only persists changes if all validations pass. Check the Home Assistant logs for specific error messages.

Best Practices

When Setting Up Shadow Kids

✅ Enable parent chore assignment first before attempting to link
✅ Verify names match exactly (use "Manage Kids" and "Manage Parents" to check)
✅ Test with one parent-kid pair before automating
✅ Check entity states after linking to confirm data preservation

When Managing Shadow Relationships

✅ Use the options flow for simple cases (creating new shadow kids)
✅ Use the service for migrations (linking existing kid profiles)
✅ Document why you're using shadow kids (add notes to parent/kid descriptions)
✅ Monitor notification settings if you enable kid notifications
✅ Understand feature toggles: Workflow and gamification are enabled by default after linking; disable only if you want approval-only mode or to hide gamification features
✅ Remember data is always preserved: Disabling features only changes UI visibility, never deletes data

When Unlinking Shadow Kids

✅ Rename the "_unlinked" kid afterward for clarity
✅ Decide if you want to delete or keep the unlinked kid
✅ Update any automations that reference the old shadow kid entity IDs
✅ Re-enable parent chore assignment if you want to create a new shadow kid

Technical Details

Entity ID Stability

Linking: The kid's entity ID does NOT change. Entity IDs remain stable (e.g., sensor.sarah_kidschores_points stays sensor.sarah_kidschores_points)
Unlinking: The kid's entity ID CHANGES due to the rename (e.g., sensor.sarah_kidschores_points becomes sensor.sarah_unlinked_kidschores_points)

Device Registry Integration

The unlink operation updates Home Assistant's device registry immediately:

Device name changes from "Sarah" to "Sarah_unlinked"
All entity friendly names update automatically
No integration reload required
Changes visible instantly in the UI

Storage Updates

Both link and unlink operations:

Update the kid's data in coordinator memory
Update the parent's data in coordinator memory
Call coordinator._persist() to save to .storage/kidschores_data
Call coordinator.async_update_listeners() to refresh all entities

This ensures data consistency and immediate UI updates.

Support

If you encounter issues with the shadow kid linking service:

Check the troubleshooting section above
Review Home Assistant logs for error messages
Open an issue on GitHub with:
- Your Home Assistant version
- KidsChores integration version
- Complete error message
- Steps to reproduce

Remember: The linking service is designed to be safe and non-destructive. All data is preserved during both link and unlink operations.

Service: Shadow Kid Linking User Guide - ad-ha/kidschores-ha GitHub Wiki

Shadow Kid Linking Service - User Guide

Overview

What Are Shadow Kids?

When to Use This Service

Prerequisites

Service Operations

Link Operation

Parameters

What Happens During Linking

Data Preservation Guarantee

What About Workflow and Gamification Features?

Unlink Operation

Parameters

What Happens During Unlinking

The "_unlinked" Suffix

Step-by-Step Examples

Example 1: Link Existing Profiles

Example 2: Unlink Shadow Kid

Example 3: Migrating from Workaround Setup

Notification Behavior

Default Settings

Enabling Notifications for Shadow Kids

Error Messages and Troubleshooting

Common Error Messages

"No kid found with name 'Sarah'"

"No parent found with name 'Sarah'"

"Kid 'Sarah' is already linked to a parent"

"Parent 'Sarah' already has a different shadow kid linked"

"Kid 'Sarah' is not linked to any parent"

"Parent 'Sarah' does not have chore assignment enabled"

General Troubleshooting Tips

Advanced Usage

Automations and Scripts

Example: Auto-link on parent creation

Example: Scheduled unlinking

Integration with Other Services

FAQ

Q: Will linking delete my kid's data?

Q: What happens to points when I link a kid?

Q: What happens if I disable workflow or gamification features?

Q: Can I have multiple shadow kids for one parent?

Q: Can a shadow kid be linked to multiple parents?

Q: Why does the kid get renamed to "_unlinked" when I unlink?

Q: Do I need to reload the integration after linking/unlinking?

Q: What if I manually delete a shadow kid?

Q: Can I link a kid that already has chores assigned?

Q: What happens to notifications when I link a kid?

Q: Can I use the service with kids/parents that have special characters in their names?

Q: What if the linking service fails partway through?

Best Practices

When Setting Up Shadow Kids

When Managing Shadow Relationships

When Unlinking Shadow Kids

Technical Details

Entity ID Stability

Device Registry Integration

Storage Updates

Related Documentation

Support