> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluid.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract.
> Authenticate with the header Authorization: Bearer <token>; public storefront read endpoints require no auth.
> Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null.
> When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. /api/company/v1 and /api/v1/... paths are documented in no spec here and must never be used (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only where a spec documents it — in practice the unversioned company-v0 admin surface; every versioned surface uses cursor pagination.
> Navigation menu management is documented in themes/navigation-menus. These unversioned admin endpoints (/api/menus and nested menu_items) are verified against the implementation but are not yet in the synced OpenAPI specs. Use that reference for menu payloads and its flat page/per_page pagination; missing spec coverage does not make these endpoints unavailable.
> The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country).
> api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.
> Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other.
> For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces.
> Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings.
> Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties.
> Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables.
> A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation.

# Member sites manifest

> Edit member sites, access rules, pages, and navigation in members_sites.json and preview changes with the theme CLI.

<Warning>
  Member storefront is in a limited pilot. Use a company with member storefront enabled and a current Fluid theme CLI that supports version 2 manifests.
</Warning>

`members_sites.json` is the portable member configuration at the **theme root**. It contains sites, access rules, page bindings, and complete navigation trees. Liquid, sections, layouts, and their settings remain in separate theme files.

Use this file to change navigation from your editor or a coding agent such as Mist. You do not need to recreate the menu in the admin after each edit.

<Warning>
  An upload is a **complete snapshot**, not a patch. Sites and pages omitted from the document are removed from the receiving theme. Start from the manifest pulled or exported from your theme, and preserve unrelated entries when editing one menu.
</Warning>

## Edit navigation with theme dev

1. Start with your theme's current files, including `members_sites.json` and its referenced templates.
2. Run `fluid theme dev` from the theme directory. By default, it creates or reuses an isolated development theme. `--theme` explicitly targets an existing theme; check the target before using it.
3. Find your site in `sites`. Follow its `menu_key` to the matching entry in `menus`.
4. Edit that menu's `items`: change a `title`, update a `target`, reorder the array, or add nested `children`. Preserve every required field and keep keys unique.
5. Save the manifest. Wait for `synced members_sites.json` in the CLI output.
6. Check the CLI preview. With live reload enabled, it reloads after a successful upload and renders the updated menu.

The watcher submits the member document and its required local template dependencies together. Invalid member data or a missing dependency rejects the member upload, rather than applying only part of it. A concurrent remote edit can block the transfer; pull and reconcile the changes before retrying.

Mist's theme development workflow uses the same CLI watcher. An agent saving the file triggers the same upload as a manual edit. The CLI preview reloads automatically; a separately opened admin builder may need a refresh.

<Note>
  The layout must render the site's menu, usually through `settings.menu`. Editing the manifest cannot change hardcoded navigation HTML. See [Member sites](/themes/member-storefront/member-sites#arrange-the-navigation) for rendering behavior.
</Note>

## Document structure

Use the exact filename **`members_sites.json`**, including the `s` in `members`. Put it next to root-level `variables.json`, not inside `config/`.

All five top-level fields are required:

| Field             | Meaning                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `version`         | Integer `2`.                                                                                    |
| `sites`           | Complete list of member sites and their custom pages.                                           |
| `menus`           | Full navigation trees used by those sites or declared menu settings.                            |
| `templates`       | Metadata for member templates and their dependencies. Template content stays in separate files. |
| `menu_references` | Links between menu settings in theme files and entries in `menus`.                              |

Each object uses an exact set of fields. Include empty arrays, empty objects, or `null` where allowed; do not add your own fields. Document keys are portable references, not database IDs. Keep them stable while editing, but note that existing sites are matched by **name**, and pages by **slug within their site**. Changing a site name or page slug replaces that entry rather than performing an in-place rename.

### Example: a customer menu

This complete example defines one customer site with two navigation links. It assumes the destination company has an active `customer` member type and the `US` country, and that `layouts/member.liquid` exists and renders `settings.menu` without additional selected menu settings. It has no custom pages or template metadata overrides.

**Use it as a format example. Do not replace an existing multi-site manifest with it to edit one link.**

```json theme={null}
{
  "version": 2,
  "sites": [
    {
      "key": "customer-site",
      "name": "Customer",
      "active": true,
      "default": false,
      "position": 0,
      "layout_name": "member",
      "rule": {
        "country_codes": ["US"],
        "member_type_slugs": ["customer"]
      },
      "menu_key": "customer-menu",
      "pages": []
    }
  ],
  "menus": [
    {
      "key": "customer-menu",
      "handle": "customer-navigation",
      "title": "Customer navigation",
      "active": true,
      "country_codes": ["US"],
      "items": [
        {
          "key": "customer-shop",
          "title": "Shop",
          "titles": {},
          "target": { "type": "Shop" },
          "children": []
        },
        {
          "key": "customer-support",
          "title": "Contact support",
          "titles": {},
          "target": { "type": "Link", "url": "mailto:support@acme.com" },
          "children": []
        }
      ]
    }
  ],
  "templates": [],
  "menu_references": []
}
```

To rename **Contact support** to **Get help**, change that item's `title` and save. If the item has translated labels in `titles`, update those labels too. To place it before **Shop**, move the whole item earlier in the `items` array.

## Sites and access rules

Each site requires these fields:

| Field         | Meaning                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `key`         | Unique site reference within the document.                                                                               |
| `name`        | Unique site name within the theme; also used to match an existing site.                                                  |
| `active`      | Boolean. Inactive sites do not match members.                                                                            |
| `default`     | Boolean. Marks a fallback site, considered after explicit sites. Use `false` for an ordinary audience-specific site.     |
| `position`    | Integer controlling site resolution order.                                                                               |
| `layout_name` | Layout name without directory or extension; `null` uses the normal layout fallback. `"none"` opts out of a theme layout. |
| `rule`        | Object containing `country_codes` and `member_type_slugs` arrays.                                                        |
| `menu_key`    | Key of an entry in `menus`, or `null` for no assigned menu.                                                              |
| `pages`       | Array of custom member page definitions.                                                                                 |

Rules use country codes such as `US` and `CA`, and member-type slugs such as `customer` and `rep`. Fluid resolves them against the receiving company. A missing country or missing/archived member type rejects the upload; it does not silently clear the restriction.

An empty rule axis is unconstrained. Clearing `member_type_slugs` broadens access; use `active: false` to disable a site. Country and member-type restrictions both apply when both are present. See [Site access rules](/themes/member-storefront/member-sites#decide-who-a-site-serves).

## Custom pages

Every entry in a site's `pages` array requires:

| Field           | Meaning                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------- |
| `key`           | Page reference unique across all sites in this document.                                  |
| `title`         | Display title.                                                                            |
| `slug`          | Lowercase letters, numbers, and hyphens; unique within the site.                          |
| `published`     | Boolean controlling whether the member page is published.                                 |
| `template_path` | Relative path such as `members_page/rewards/index.liquid`, or `null` for an unbound page. |

For example, add this object to the intended site's `pages` array and include its template file in the theme:

```json theme={null}
{
  "key": "customer-rewards",
  "title": "Rewards",
  "slug": "rewards",
  "published": true,
  "template_path": "members_page/rewards/index.liquid"
}
```

A non-null template reference must resolve. Listing a path does not create the file's content. Preserve its exported template metadata and dependencies as well.

System screens are Fluid-provided destinations. Link to them with a `MembersScreen` target; do not create custom page entries to represent them.

## Menus and nested items

Each menu requires `key`, `handle`, `title`, `active`, `country_codes`, and `items`.

* `key` connects the menu to sites and declared settings.
* `handle` is the preferred menu slug. An unrelated existing menu with that slug is not a prerequisite. Fluid can create a new menu and allocate a different handle on a collision.
* `country_codes` must contain at least one country available in the receiving company. Unlike a site's country rule, this cannot be empty.
* `items` is ordered. Each item requires `key`, `title`, `titles`, `target`, and `children`.
* Item keys must be unique across all menus. `titles` maps locales to translated labels, such as `{"en": "Shop", "fr": "Boutique"}`. Use `{}` when there are no translations.
* `children` contains more items of the same shape. Use `[]` for a leaf.

Every declared menu must be referenced by a site's `menu_key` or a `menu_references` entry. Fluid preserves shared menus by creating a separate copy when an edit would otherwise change another consumer's navigation. Declared menu settings are rewritten to the allocated handle. Avoid hardcoding a handle that must survive a cross-company import.

### Link targets

| Destination          | `target` shape                                                                         |
| -------------------- | -------------------------------------------------------------------------------------- |
| Custom member page   | `{"type": "MembersPage", "site_key": "customer-site", "page_key": "customer-rewards"}` |
| System screen        | `{"type": "MembersScreen", "key": "messaging"}`                                        |
| Explicit URL         | `{"type": "Link", "url": "https://acme.com/help"}`                                     |
| Company content      | `{"type": "Product", "handle": "starter-kit"}`                                         |
| Built-in destination | `{"type": "Shop"}`                                                                     |

A `MembersPage` target must name a page belonging to the referenced site. A `MembersScreen` key must be a supported system screen, and the destination company must have the account screens runtime configured.

Handle-based target types are `Product`, `Medium`, `Page`, `EnrollmentPack`, `Collection`, `Post`, and `Library`. Their content must already exist in the receiving company; the manifest does not transfer products or media.

Built-in target types are `HomePage`, `CollectionPage`, `CategoryPage`, `JoinPage`, `Shop`, and `PostPage`. These take only `type`.

Explicit links accept HTTP, HTTPS, `mailto:`, `tel:`, root-relative paths, and fragment links. Prefer `MembersPage` or `MembersScreen` targets for member destinations so Fluid resolves their routes.

## Template metadata and menu settings

Keep the `templates` and `menu_references` entries produced by a pull or export when editing navigation. They preserve template behavior and selected menus across imports.

A `templates` entry requires these fields:

| Field                          | Meaning                                                                                            |
| ------------------------------ | -------------------------------------------------------------------------------------------------- |
| `path`                         | Relative member template or dependency path.                                                       |
| `status`                       | Template status from the exported theme. Preserve it unless intentionally changing template state. |
| `default`                      | Boolean marking the default template for its type.                                                 |
| `head`                         | Head content, including an empty string, or `null`.                                                |
| `translations`                 | Exported translations object.                                                                      |
| `format`                       | `"liquid"` or `"json"`.                                                                            |
| `static_content`               | Boolean retaining the template's static-content setting.                                           |
| `hide_navbar`                  | Boolean retaining the template's navbar setting.                                                   |
| `use_active_application_theme` | Boolean retaining its active-theme setting.                                                        |

These entries carry metadata, not Liquid bodies. Keep the separate template, layout, section, snippet, and settings files they depend on. Only templates belonging to the member composition can be declared here.

`menu_references` describes selected `link_list` settings. Each entry requires:

| Field      | Meaning                                                                      |
| ---------- | ---------------------------------------------------------------------------- |
| `path`     | Theme file containing the setting.                                           |
| `location` | `"json"` for JSON content or `"schema"` for a Liquid schema block.           |
| `pointer`  | JSON Pointer to the selected menu value within that JSON document or schema. |
| `menu_key` | Key of the menu in `menus`.                                                  |

Every selected menu setting in the member composition needs exactly one matching reference. Use the references emitted by export or pull instead of guessing a pointer. If you add a new selected menu setting, add its reference and include the containing file.

## Upload, import, and removal behavior

For a company theme, uploading the manifest updates that theme's member configuration. Downloading it again reconstructs the document from the current sites, pages, menus, and templates.

* Re-uploading unchanged configuration retains unchanged records.
* Sites match by name; pages match by slug within their site. Document keys connect references within the file and are not persistent record identities.
* Sites and pages omitted from a version 2 snapshot are removed. Removal can be rejected if a removed page is still referenced by another menu consumer.
* Missing templates, unresolved content handles, invalid rules, and malformed documents reject the member upload.
* Deleting or renaming `members_sites.json` is rejected. To intentionally clear the target theme's member sites and pages, submit an explicit empty version 2 document. This is not a request to delete every company menu or theme file.

```json theme={null}
{
  "version": 2,
  "sites": [],
  "menus": [],
  "templates": [],
  "menu_references": []
}
```

Older array-based exports do not include a complete portable menu tree. Re-export or pull a version 2 document before editing navigation; a legacy `menu_slug` alone cannot reconstruct a menu in another company.

## Troubleshooting

| Symptom                                              | What to check                                                                                                                                                |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Saving does not trigger an upload                    | Use the exact root filename `members_sites.json`, check `.fluidignore`, and confirm the CLI is watching this directory.                                      |
| CLI says the member dependency is unavailable        | Include all declared template files locally and remove ignore rules that exclude required dependencies.                                                      |
| Upload fails after adding a country or member type   | Use codes and slugs available in the target company. Do not use database IDs.                                                                                |
| CLI reports an incomplete transfer                   | Correct the reported error and restart `fluid theme dev` as instructed. A rejected member transfer blocks later writes in that session.                      |
| Navigation stays unchanged after a successful upload | Check the CLI's target theme, reload the correct preview, confirm the member resolves to the intended site, and verify the layout renders its assigned menu. |
| The admin builder still shows the previous menu      | Refresh that builder. The CLI's automatic reload applies to its own preview.                                                                                 |
| A menu handle changes after import                   | Fluid allocated a separate menu to avoid a collision or protect a shared menu. Use the site's assigned menu or declared menu settings.                       |

## Task brief for coding agents

```text theme={null}
Edit navigation for the Customer member site in this theme.
Read the existing members_sites.json first. Follow the site's menu_key to its menu.
Preserve all other sites, pages, menus, template metadata, and menu references.
Change only the requested menu labels, destinations, ordering, or children.
Keep keys unique and use portable targets instead of database IDs.
Save the complete manifest while fluid theme dev is running.
Wait for the successful sync message and inspect the CLI preview.
Report any upload error instead of claiming the preview changed.
Do not target or publish a live theme unless that action is authorized.
```