Forked Households

A Forked Household is a separate private iCloud share for collaborative meal plans and shopping.

The owner needs verified Forked Pro to create and manage a Household. Up to four invited participants can join for free. Every participant needs:

• Forked on an iPhone
• An available iCloud account with iCloud Drive
• Their own connection and credentials for the same Mealie recipe library

Apple Family Sharing for a Pro purchase is separate from Forked Household membership.

Open Profile → Households. The owner can create a Household, invite people with Apple’s private sharing sheet, remove participants, or dissolve it.

An invitee taps the iCloud link; Forked opens and shows Joining Household… while it joins. A pending invitation, iCloud problem, active sync, library mismatch, or read-only Household is shown with text and a symbol. You can defer the Finish Joining sheet with Not Now and return through Household settings.

The organizer chooses whether to publish the current Plan or Shopping list. Each invited member chooses whether to replace their local data before that feature begins syncing. Their selected profile name and emoji are shared.

Shared:

• The Household name and membership state
• Narrow plan fields such as recipe identifier and title, servings, completion and placement
• Shopping item fields, deletion markers, and conflict metadata

Household metadata, each membership, and the owner-controlled editable or read-only state are separate stamped records, so stale member or aggregate data cannot replace an owner removal or access restriction. Membership includes an app-generated owner ID or Apple-provided CloudKit participant IDs, selected member names and optional emoji, owner and editor roles, joined and removed times, and an opaque random identifier that distinguishes each accepted membership invite. Conflict stamps include a modification time and the acting Household member ID.

Not shared: Mealie user IDs, recipe-server credentials or raw server addresses, recipe bodies or caches, dietary preferences, or Plan History.

After you choose whether to replace your local Plan or Shopping for the exact Household generation, the shared changes appear in the ordinary Plan and Shopping tabs. Member name and emoji and last-editor text identify shared edits. Plan History remains local.

Sync is eventually consistent: a member with an incomplete recipe index can fetch the referenced recipes directly from the connected server. An offline cache miss keeps setup pending; only verified same-library absence can produce an unavailable recipe slot. While an accepted Plan replacement is pending, local Plan edits are blocked to protect your work. Use Try Again in the Plan banner to retry.

Paused means Plan or Shopping sync is stopped on this device. Your local list stays available; tap Resume to share again. When the organizer turns a sync off, it stays off until the organizer turns it back on.

Finishing setup shows while a member’s iPhone fills in the shared plan’s recipes. If that member’s Mealie sign-in has stopped working, Forked uses the recipes already on the iPhone and asks them to sign in again.

Forked keeps a local Household replica and queues edits while offline. It retries when the app launches or returns to the foreground and iCloud is available; a visible Retry sync button and pull-to-refresh provide manual alternatives. CloudKit notifications can prompt an earlier refresh, but delivery may be delayed or coalesced. Foreground refresh and manual retry remain the fallback. Foreground sync is bounded and separate from recipe-server sync. Do not assume another device has an offline change until both devices have reconnected and completed Household sync.

When several people edit at once, changes to different fields merge. When two people change the same field, Forked uses a consistent version order so devices settle on the same value. Deleting a shared meal or shopping item takes precedence over edits to that same item, including delayed offline edits. To bring it back, add it again. Devices can show different states while offline or catching up; shared content settles after everyone reconnects and completes sync.

Every participant must independently connect Forked to the same Mealie library. Forked compares a one-way digest made with a fresh random salt for that Household; only the salt and digest are shared. The raw server address and credentials are never put in the Household share. The accepted Household remains readable, but shared edits stay blocked until the connection matches or the owner removes that participant. A shared plan recipe that is not in the local library shows Unavailable in your recipe library instead of another person’s recipe content.

Changing credentials or connecting to another Mealie library does not leave or dissolve the Household. Forked retains its private-share association and access policy, shows the Household read-only with a mismatch message, and can rehydrate shared plans and shopping after you reconnect to the matching library.

If the owner’s verified Pro entitlement ends, the owner app queues the shared read-only policy on its next entitlement refresh and syncs it when possible. Members then pause shared sync and keep ordinary Plan and Shopping editable locally. After restoring Pro, choose Restore editing, then enable each feature again, using their current data; invited members must accept replacement again.

Forked has no account server or App Store Server Notifications, so this change cannot be enforced instantly if the owner’s device never reconnects. Support cannot remotely administer or recover a Household.

Action	Who	What happens
Leave Household	A participant	After iCloud confirms the leave, Forked clears that Household’s local replica.
Remove a participant	The owner	Revokes that iCloud account’s future access. It cannot remotely erase a copy already cached on the participant’s iPhone.
Dissolve Household	The owner	Deletes the private shared iCloud zone.
Stop Sharing (Apple’s sheet)	The owner	iCloud revokes the participants right away, and Forked queues owner-authorized removals for every former member. The owner keeps the local Household and can create a fresh private share later.

When a removed participant’s app detects revoked access, it clears the selected Household and its shared replica, shows a membership-ended notice, and preserves the ordinary local Plan and Shopping list. The removed participant can join again only by accepting a fresh owner invite; stale offline edits from the prior membership cannot restore access or replace the renewed membership.

None of these actions deletes anyone’s personal recipes, credentials, profiles, personal plans, Plan History, or personal Shopping list.

Use the share action in the ordinary Shopping tab to export list text through the iOS share sheet. Leaving a Household or disabling sync retains the latest Plan and Shopping data locally; later local edits are private.

Leave to remove your membership; the organizer can dissolve the Household to delete the shared iCloud zone. Use Profile → Settings → Disconnect & Reset, or delete Forked, to clear cached Forked data from one device.